afterpython 0.1.0.dev17__tar.gz → 0.1.0rc0__tar.gz

{afterpython-0.1.0.dev17 → afterpython-0.1.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afterpython
-Version: 0.1.0.dev17
+Version: 0.1.0rc0
 Summary: CLI tool to streamline Python package maintenance and generate a dedicated project website
 Keywords: package-maintenance,project-website,static-site-generator,developer-tools,documentation,cli-tool,ci/cd,mystmd,semantic-release,python-packaging
 Author: Stephen Yau
@@ -20,12 +20,11 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: tomlkit>=0.13.3
 Requires-Dist: ruamel-yaml>=0.18.16
 Requires-Dist: gitpython>=3.1.45
-Requires-Dist: pygithub>=2.8.1
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pyproject-metadata>=0.10.0
-Requires-Dist: mystmd>=1.6.6
+Requires-Dist: mystmd>=1.7.0
 Requires-Dist: pdoc>=16.0.0
-Requires-Dist: ruff>=0.14.6
+Requires-Dist: ruff>=0.14.8
 Requires-Dist: pre-commit>=4.5.0
 Requires-Dist: commitizen>=4.10.0
 Requires-Python: >=3.11
@@ -105,6 +104,17 @@ ap init
 ```
 
 
+---
+## CLI Commands
+```bash
+# show all commands
+ap --help
+
+# or use terminal UI (TUI)
+ap tui
+```
+
+
 ---
 ## Tech Stack
 - [MyST]
@@ -119,8 +129,3 @@ ap init
 - [WebLLM]
 <!-- - ty -->
 <!-- - [pixi] -->
-
-
----
-## *Our Mission*
-> Only by making package maintenance and documentation easy can we encourage more Python developers to publish their own packages and grow the ecosystem even further.

{afterpython-0.1.0.dev17 → afterpython-0.1.0rc0}/README.md

@@ -69,6 +69,17 @@ ap init
 ```
 
 
+---
+## CLI Commands
+```bash
+# show all commands
+ap --help
+
+# or use terminal UI (TUI)
+ap tui
+```
+
+
 ---
 ## Tech Stack
 - [MyST]
@@ -83,8 +94,3 @@ ap init
 - [WebLLM]
 <!-- - ty -->
 <!-- - [pixi] -->
-
-
----
-## *Our Mission*
-> Only by making package maintenance and documentation easy can we encourage more Python developers to publish their own packages and grow the ecosystem even further.

{afterpython-0.1.0.dev17 → afterpython-0.1.0rc0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "afterpython"
-version = "0.1.0.dev17"
+version = "0.1.0rc0"
 description = "CLI tool to streamline Python package maintenance and generate a dedicated project website"
 license = "Apache-2.0"
 authors = [
@@ -38,14 +38,14 @@ dependencies = [
     "tomlkit>=0.13.3",
     "ruamel-yaml>=0.18.16",
     "gitpython>=3.1.45",
-    "pygithub>=2.8.1",
+    # "pygithub>=2.8.1",
     "python-dotenv>=1.2.1",
     "pyproject-metadata>=0.10.0",
     # "jupytext>=1.18.1",
     # "jinja2>=3.1.6",
-    "mystmd>=1.6.6",
+    "mystmd>=1.7.0",
     "pdoc>=16.0.0",
-    "ruff>=0.14.6",
+    "ruff>=0.14.8",
     "pre-commit>=4.5.0",
     "commitizen>=4.10.0",
     # "python-semantic-release>=10.5.2",
@@ -65,7 +65,7 @@ pcu = "afterpython.main:run_pcu"
 override-dependencies = ["platformdirs>=4.5.0", "nodeenv>=1.9.1"]
 
 [build-system]
-requires = ["uv_build>=0.9.13,<0.10.0"]
+requires = ["uv_build>=0.9.16,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

afterpython-0.1.0rc0/src/afterpython/builders/__init__.py

@@ -0,0 +1,17 @@
+from afterpython.builders.content_json import build_content_json
+from afterpython.builders.index_md import (
+    create_placeholder_index_md_files,
+    delete_placeholder_index_md_files,
+)
+from afterpython.builders.jupyter_notebook import build_jupyter_notebooks
+from afterpython.builders.markdown import build_markdown
+from afterpython.builders.metadata import build_metadata
+
+__all__ = (
+    "build_content_json",
+    "build_jupyter_notebooks",
+    "build_markdown",
+    "build_metadata",
+    "create_placeholder_index_md_files",
+    "delete_placeholder_index_md_files",
+)

afterpython-0.1.0rc0/src/afterpython/builders/content_json.py

@@ -0,0 +1,131 @@
+"""
+Build {content_type}.json for non-doc content type (blog, tutorial, example, guide)
+
+Combines all individual content JSON files from MyST build output into a single
+manifest file for SvelteKit to consume (e.g., blog.json, tutorial.json).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from afterpython._typing import tContentType
+
+import json
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+
+
+def standardize_data(content_type: tContentType, content: dict) -> dict:
+    """
+    Standardize the content dictionary to a single level.
+    """
+    from afterpython.tools._afterpython import read_afterpython
+
+    afterpython = read_afterpython()
+    website = afterpython.get("website", {})
+    content_type_config = website.get(content_type, {})
+    featured_post = content_type_config.get("featured_post", "")
+
+    frontmatter = content.get("frontmatter", {})
+    # e.g. featured_post = "blog4.md" or "blog4"
+    is_featured = content["slug"] == featured_post or content["location"].endswith(
+        featured_post
+    )
+    return {
+        "version": content["version"],
+        "slug": content["slug"],
+        "location": content["location"],
+        "featured": is_featured,
+        # frontmatter fields
+        "title": frontmatter.get("title", ""),
+        "description": frontmatter.get("description", ""),
+        "tags": frontmatter.get("tags", []),
+        "date": frontmatter.get("date", ""),
+        "thumbnail": frontmatter.get("thumbnail", ""),
+        "thumbnailOptimized": frontmatter.get("thumbnailOptimized", ""),
+        "authors": frontmatter.get("authors", []),
+    }
+
+
+def convert_paths(content_type: tContentType, output_file: Path):
+    """
+    Convert paths (generated by MyST build) in the content_json file to use the new paths in the build output.
+    e.g. convert /blog_thumbnail-08d4f63a34eb7b55b6a00c25218c3295.png to /blog/build/blog_thumbnail-08d4f63a34eb7b55b6a00c25218c3295.png
+    """
+    with open(output_file, encoding="utf-8") as f:
+        content = json.load(f)
+
+    for item in content:
+        if not item.get("thumbnailOptimized"):
+            item["thumbnailOptimized"] = item["thumbnail"]
+        item["thumbnail"] = f"/{content_type}/build" + item["thumbnail"]
+        item["thumbnailOptimized"] = (
+            f"/{content_type}/build" + item["thumbnailOptimized"]
+        )
+
+    with open(output_file, "w", encoding="utf-8") as f:
+        json.dump(content, f, indent=2, ensure_ascii=False)
+
+    click.echo(f"Completed path conversion in {output_file}")
+
+
+def build_content_json():
+    """Build {content_type}.json manifest for non-doc content types.
+
+    Reads all JSON files from afterpython/_build/{content_type}/site/content/
+    (excluding index.json) and combines them into a single manifest file at
+    afterpython/_build/{content_type}.json.
+
+    This manifest is used by SvelteKit landing pages to list all content items.
+
+    Args:
+        content_type: Content type (blog, tutorial, example, guide)
+    """
+    for content_type in CONTENT_TYPES:
+        if content_type == "doc":
+            continue  # Doc doesn't need a combined manifest
+
+        content_path = ap.paths.afterpython_path / content_type
+        content_dir = content_path / "_build" / "site" / "content"
+        myst_yml_path = content_path / "myst.yml"
+        if (
+            not content_path.exists()
+            or not myst_yml_path.exists()
+            or not content_dir.exists()
+        ):
+            click.echo(f"Skipping {content_type}.json (missing files)")
+            continue
+
+        click.echo(f"Building {content_type}.json...")
+
+        # Collect all JSON files except index.json, which is created by a placeholder index.md file
+        content_items = []
+        for json_file in content_dir.glob("*.json"):
+            if json_file.stem == "index":
+                continue  # Skip index.json
+
+            try:
+                with open(json_file, encoding="utf-8") as f:
+                    data = json.load(f)
+
+                # Preserve all data from MyST JSON files
+                # The project-website-template will parse the fields it needs
+                content_items.append(standardize_data(content_type, data))
+            except (json.JSONDecodeError, KeyError) as e:
+                click.echo(f"Warning: Failed to parse {json_file}: {e}")
+                continue
+
+        # Write combined manifest
+        output_file = ap.paths.build_path / f"{content_type}.json"
+        with open(output_file, "w", encoding="utf-8") as f:
+            json.dump(content_items, f, indent=2, ensure_ascii=False)
+
+        click.echo(f"Generated {output_file} with {len(content_items)} items")
+
+        convert_paths(content_type, output_file)

afterpython-0.1.0rc0/src/afterpython/builders/index_md.py

@@ -0,0 +1,94 @@
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+
+
+def create_placeholder_index_md_files():
+    """Create placeholder index.md files for non-doc content types.
+
+    Without these placeholders, MyST treats the first file in TOC as index,
+    causing it to use routes like /blog instead of /blog/blog1. These routes
+    are reserved for SvelteKit landing pages. Placeholders ensure all actual
+    content files get proper slugs and are deleted post-build.
+    """
+    from afterpython._io.yaml import read_yaml, write_yaml
+    from afterpython.tools.myst import _write_index_file
+
+    for content_type in CONTENT_TYPES:
+        if content_type == "doc":
+            continue  # Doc doesn't need a placeholder index.md
+
+        content_path = ap.paths.afterpython_path / content_type
+        if not content_path.exists():
+            click.echo(
+                f"No content found in {content_path}, skip creating placeholder index.md"
+            )
+            continue
+
+        myst_yml_path = content_path / "myst.yml"
+        if not myst_yml_path.exists():
+            click.echo(
+                f"No myst.yml found in {content_path}, skip creating placeholder index.md"
+            )
+            continue
+
+        content_path = ap.paths.afterpython_path / content_type
+        myst_yml_path = content_path / "myst.yml"
+
+        # Prepend index.md to TOC in myst.yml
+        if myst_yml_path.exists():
+            # Create placeholder index.md file
+            _write_index_file(content_type)
+            myst_data = read_yaml(myst_yml_path) or {}
+            toc = myst_data.get("project", {}).get("toc", [])
+
+            # Check if index.md is already first in TOC
+            if not toc or toc[0].get("file") != "index.md":
+                # Prepend index.md to TOC in myst.yml
+                new_toc = [{"file": "index.md"}, *toc]
+                if "project" not in myst_data:
+                    myst_data["project"] = {}
+                myst_data["project"]["toc"] = new_toc
+                write_yaml(myst_yml_path, myst_data)
+                click.echo(f"Added index.md to TOC in {myst_yml_path}")
+
+
+def delete_placeholder_index_md_files():
+    """Delete placeholder index.md and built index.html for non-doc content types.
+
+    These files were created pre-build to ensure proper slug generation. Now that
+    MyST has built the content with correct slugs, we delete them so SvelteKit
+    can own the landing page routes (/blog, /tutorial, etc.) in the project website.
+    """
+    from afterpython._io.yaml import read_yaml, write_yaml
+
+    for content_type in CONTENT_TYPES:
+        if content_type == "doc":
+            continue  # Doc doesn't need a placeholder index.md
+
+        content_path = ap.paths.afterpython_path / content_type
+        myst_yml_path = content_path / "myst.yml"
+        index_md = content_path / "index.md"
+
+        # Delete index.md from source
+        if index_md.exists():
+            index_md.unlink()
+            click.echo(f"Deleted: {index_md}")
+
+        # Delete index.html from build output
+        index_html = content_path / "_build" / "html" / "index.html"
+        if index_html.exists():
+            index_html.unlink()
+            click.echo(f"Deleted: {index_html}")
+
+        # Remove index.md from TOC in myst.yml
+        if myst_yml_path.exists():
+            myst_data = read_yaml(myst_yml_path) or {}
+            toc = myst_data.get("project", {}).get("toc", [])
+
+            # Remove index.md from TOC if it's the first entry
+            if toc and toc[0].get("file") == "index.md":
+                myst_data["project"]["toc"] = toc[1:]
+                write_yaml(myst_yml_path, myst_data)
+                click.echo(f"Removed index.md from TOC in {myst_yml_path}")

afterpython-0.1.0rc0/src/afterpython/builders/jupyter_notebook.py

@@ -0,0 +1,293 @@
+import json
+import os
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+from afterpython.tools.pyproject import read_metadata
+
+
+def _get_molab_badge() -> str:
+    return "https://marimo.io/molab-shield.svg"
+
+
+def _create_molab_url(github_url: str, content_path: Path):
+    """Create a molab URL for a given content type and notebook path.
+    Args:
+        github_url: str, e.g. "https://github.com/AfterPythonOrg/afterpython"
+        content_path: str, e.g. "tutorial/test.ipynb"
+    """
+    github_url = github_url.replace("https://github.com/", "github/")
+    return f"https://molab.marimo.io/{github_url}/blob/main/afterpython/{content_path.as_posix()}"
+
+
+def _read_notebook(notebook_path: Path, content_path: Path) -> dict | None:
+    """Read and validate a Jupyter notebook.
+
+    Returns:
+        Notebook dict if valid, None if invalid or error occurred
+    """
+    try:
+        with open(notebook_path) as f:
+            notebook = json.load(f)
+    except json.JSONDecodeError:
+        click.echo(f"✗ Skipping {content_path} - invalid or empty JSON")
+        return None
+    except Exception as e:
+        click.echo(f"✗ Error reading {content_path}: {e}")
+        return None
+
+    # Validate notebook structure
+    if "cells" not in notebook:
+        click.echo(f"✗ Skipping {content_path} - not a valid Jupyter notebook")
+        return None
+
+    return notebook
+
+
+def _write_notebook(notebook: dict, notebook_path: Path):
+    """Write a notebook dict to file."""
+    with open(notebook_path, "w") as f:
+        json.dump(notebook, f, indent=1)
+
+
+def _has_frontmatter(notebook: dict) -> bool:
+    """Check if a notebook has frontmatter in the first cell."""
+    if not notebook["cells"]:
+        return False
+
+    first_cell = notebook["cells"][0]
+    return (
+        first_cell.get("cell_type") == "markdown"
+        and first_cell.get("source")
+        and isinstance(first_cell["source"], list)
+        and len(first_cell["source"]) > 0
+        and first_cell["source"][0].strip().startswith("---")
+    )
+
+
+def _read_frontmatter(notebook: dict) -> str | None:
+    """Read frontmatter content from a notebook.
+
+    Returns:
+        Frontmatter content as a string if it exists, None otherwise
+    """
+    if not _has_frontmatter(notebook):
+        return None
+
+    first_cell = notebook["cells"][0]
+    return "".join(first_cell["source"])
+
+
+def _write_frontmatter(notebook: dict, content: str):
+    """Write frontmatter content to a notebook cell.
+
+    Low-level function that handles cell manipulation.
+    If frontmatter cell exists, updates it. If not, creates a new one.
+
+    Args:
+        notebook: The notebook dict to modify
+        content: The complete frontmatter content as a string (should include --- delimiters)
+    """
+    # Convert content string to list of lines
+    source_lines = [
+        line if line.endswith("\n") else line + "\n" for line in content.split("\n")
+    ]
+    # Remove the last empty line if the content ends with \n
+    if source_lines and source_lines[-1] == "\n":
+        source_lines.pop()
+
+    if _has_frontmatter(notebook):
+        # Update existing frontmatter cell
+        notebook["cells"][0]["source"] = source_lines
+    else:
+        # Create new frontmatter cell
+        frontmatter_cell = {
+            "cell_type": "markdown",
+            "id": "frontmatter-cell",
+            "metadata": {},
+            "source": source_lines,
+        }
+        notebook["cells"].insert(0, frontmatter_cell)
+
+
+def _add_fields_to_frontmatter(notebook: dict, fields: dict[str, str]):
+    """Add or update fields in frontmatter.
+
+    High-level function that handles frontmatter field manipulation.
+    If frontmatter exists, adds new fields to it. If not, creates new frontmatter with those fields.
+
+    Args:
+        notebook: The notebook dict to modify
+        fields: A dict of fields to add/update (e.g., {"thumbnail": "null"})
+    """
+    existing_content = _read_frontmatter(notebook)
+
+    if existing_content:
+        # Parse existing frontmatter and add new fields
+        lines = existing_content.split("\n")
+
+        # Find the closing --- of frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip().startswith("---"):
+                closing_index = i
+                break
+
+        if closing_index > 0:
+            # Insert new fields before the closing ---
+            for key, value in fields.items():
+                # Check if field already exists
+                if not any(line.strip().startswith(f"{key}:") for line in lines):
+                    lines.insert(closing_index, f"{key}: {value}")
+                    closing_index += 1  # Adjust index for next insertion
+
+            new_content = "\n".join(lines)
+            _write_frontmatter(notebook, new_content)
+    else:
+        # Create new frontmatter with the provided fields
+        field_lines = [f"{key}: {value}" for key, value in fields.items()]
+        new_content = "---\n" + "\n".join(field_lines) + "\n---"
+        _write_frontmatter(notebook, new_content)
+
+
+def _add_thumbnail_to_notebook(
+    notebook: dict, thumbnail: str, content_path: Path
+) -> bool:
+    """Add thumbnail field to a single notebook's frontmatter.
+
+    Args:
+        notebook: The notebook dict to modify
+        thumbnail: The thumbnail value to add
+        content_path: Path for logging purposes
+
+    Returns:
+        True if thumbnail was added, False if it already exists
+    """
+    # Read frontmatter content
+    frontmatter_content = _read_frontmatter(notebook)
+
+    # Check if thumbnail is already set in frontmatter
+    if frontmatter_content and "thumbnail:" in frontmatter_content:
+        return False
+
+    # Add thumbnail using the fields parameter
+    _add_fields_to_frontmatter(notebook, fields={"thumbnail": thumbnail})
+
+    if frontmatter_content:
+        click.echo(
+            f"  ↳ Added 'thumbnail: {thumbnail}' to frontmatter in: {content_path}"
+        )
+    else:
+        click.echo(
+            f"  ↳ Created frontmatter with 'thumbnail: {thumbnail}' in: {content_path}"
+        )
+
+    return True
+
+
+def _add_molab_badge_to_notebook(notebook: dict, github_url: str, content_path: Path):
+    """Add a molab badge markdown cell to a single notebook.
+
+    Args:
+        notebook: The notebook dict to modify
+        github_url: The GitHub repository URL
+        content_path: Path relative to afterpython/ for generating the molab URL
+
+    Note:
+        The jupyter notebook needs to exist in the github repository first.
+        If you have renamed a notebook, you need to push the changes to the github repository first for the badge to work.
+    """
+    molab_url = _create_molab_url(github_url, content_path)
+    badge_md = f"[![Open in molab]({_get_molab_badge()})]({molab_url})"
+
+    # Create a markdown cell with the badge
+    badge_cell = {
+        "cell_type": "markdown",
+        "id": "molab-badge-cell",  # Unique ID for the badge cell
+        "metadata": {
+            "tags": ["molab", "hide-input"]  # Optional: use MyST tags
+        },
+        "source": [badge_md],
+    }
+
+    # Determine insertion position (after frontmatter if it exists)
+    insert_position = 1 if _has_frontmatter(notebook) else 0
+
+    # Check if badge already exists at the expected position
+    if (
+        len(notebook["cells"]) > insert_position
+        and notebook["cells"][insert_position].get("id") == "molab-badge-cell"
+    ):
+        # Update existing badge
+        notebook["cells"][insert_position] = badge_cell
+        click.echo(f"✓ Updated molab badge in: {content_path}")
+    else:
+        # Insert at the correct position
+        notebook["cells"].insert(insert_position, badge_cell)
+        click.echo(f"✓ Added molab badge to: {content_path}")
+
+
+def build_jupyter_notebooks():
+    """Build Jupyter notebooks for all content types"""
+    from afterpython.tools._afterpython import get_default_thumbnail
+
+    # Check if molab badge feature is enabled
+    add_molab_badge = os.getenv("AP_MOLAB_BADGE", "1") == "1"
+
+    # Get GitHub URL once if needed for molab badges
+    github_url = None
+    if add_molab_badge:
+        metadata = read_metadata()
+        if "repository" in metadata.urls:
+            github_url = metadata.urls["repository"]
+        else:
+            click.echo(
+                "⚠ Repository URL not found in [project.urls] in pyproject.toml, skipping molab badge"
+            )
+            add_molab_badge = False
+
+    for content_type in CONTENT_TYPES:
+        click.echo(f"Building Jupyter notebooks for {content_type}/...")
+
+        path = ap.paths.afterpython_path / content_type.lower()
+
+        # Iterate over all .ipynb files once
+        for notebook_path in path.rglob("*.ipynb"):
+            # Skip files in _build directory
+            if "_build" in notebook_path.parts:
+                continue
+
+            # Get path relative to afterpython/
+            content_path = notebook_path.relative_to(ap.paths.afterpython_path)
+
+            # Get default thumbnail for this content type
+            # explicitly set to "null" if no default thumbnail is set to avoid using the first image (very likely to be "open in molab" badge image) as thumbnail
+            default_thumbnail = (
+                get_default_thumbnail(content_type, notebook_path) or "null"
+            )
+
+            # Read the notebook
+            notebook = _read_notebook(notebook_path, content_path)
+            if notebook is None:
+                continue
+
+            # Track if notebook was modified
+            modified = False
+
+            # Add molab badge if enabled
+            if add_molab_badge and github_url:
+                _add_molab_badge_to_notebook(notebook, github_url, content_path)
+                modified = True
+
+            # Add thumbnail to frontmatter
+            if content_type != "doc" and _add_thumbnail_to_notebook(
+                notebook, default_thumbnail, content_path
+            ):
+                modified = True
+
+            # Write back if modified
+            if modified:
+                _write_notebook(notebook, notebook_path)