afterpython 0.1.0.dev17__py3-none-any.whl → 0.1.1__py3-none-any.whl

afterpython/builders/markdown.py

@@ -0,0 +1,271 @@
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+
+
+def _read_markdown(markdown_path: Path, content_path: Path) -> str | None:
+    """Read and validate a markdown file.
+
+    Args:
+        markdown_path: Absolute path to the markdown file
+        content_path: Path relative to afterpython/ for logging
+
+    Returns:
+        Markdown content as a string if valid, None if invalid or error occurred
+    """
+    try:
+        with open(markdown_path, encoding="utf-8") as f:
+            content = f.read()
+        return content
+    except FileNotFoundError:
+        click.echo(f"✗ Skipping {content_path} - file not found")
+        return None
+    except Exception as e:
+        click.echo(f"✗ Error reading {content_path}: {e}")
+        return None
+
+
+def _write_markdown(content: str, markdown_path: Path):
+    """Write markdown content to file.
+
+    Args:
+        content: The markdown content to write
+        markdown_path: Absolute path to the markdown file
+    """
+    with open(markdown_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def _has_frontmatter(content: str) -> bool:
+    """Check if markdown content has frontmatter.
+
+    Args:
+        content: The markdown file content as a string
+
+    Returns:
+        True if the content starts with ---, False otherwise
+    """
+    return content.strip().startswith("---")
+
+
+def _read_frontmatter(content: str) -> str | None:
+    """Read frontmatter content from markdown.
+
+    Args:
+        content: The markdown file content as a string
+
+    Returns:
+        Frontmatter content as a string (including --- delimiters) if it exists, None otherwise
+    """
+    if not _has_frontmatter(content):
+        return None
+
+    lines = content.split("\n")
+
+    # Find the closing --- of frontmatter
+    closing_index = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            closing_index = i
+            break
+
+    if closing_index == -1:
+        return None
+
+    # Return frontmatter including both --- delimiters
+    return "\n".join(lines[: closing_index + 1])
+
+
+def _write_frontmatter(content: str, frontmatter: str) -> str:
+    """Write frontmatter content to markdown.
+
+    Low-level function that handles frontmatter replacement.
+    If frontmatter exists in content, replaces it. If not, prepends it.
+
+    Args:
+        content: The markdown file content as a string
+        frontmatter: The complete frontmatter content as a string (should include --- delimiters)
+
+    Returns:
+        The updated markdown content with the new frontmatter
+    """
+    if _has_frontmatter(content):
+        # Replace existing frontmatter
+        lines = content.split("\n")
+
+        # Find the closing --- of existing frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                closing_index = i
+                break
+
+        if closing_index > -1:
+            # Remove old frontmatter and prepend new one
+            body = "\n".join(lines[closing_index + 1 :])
+            return frontmatter + "\n" + body
+        else:
+            # Malformed frontmatter, just prepend new frontmatter
+            return frontmatter + "\n" + content
+    else:
+        # No frontmatter exists, prepend it
+        return frontmatter + "\n" + content
+
+
+def _ensure_blank_line_after_frontmatter(content: str) -> str:
+    """Ensure there's a blank line between frontmatter and content.
+
+    Args:
+        content: The markdown content
+
+    Returns:
+        Content with blank line after frontmatter if frontmatter exists
+    """
+    if not _has_frontmatter(content):
+        return content
+
+    lines = content.split("\n")
+
+    # Find the closing --- of frontmatter
+    closing_index = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            closing_index = i
+            break
+
+    if closing_index == -1:
+        return content
+
+    # Check if there's already a blank line after the closing ---, and if the next line is not empty, insert a blank line
+    if closing_index + 1 < len(lines) and lines[closing_index + 1].strip() != "":
+        lines.insert(closing_index + 1, "")
+
+    return "\n".join(lines)
+
+
+def _add_fields_to_frontmatter(content: str, fields: dict[str, 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:
+        content: The markdown file content as a string
+        fields: A dict of fields to add/update (e.g., {"thumbnail": "null"})
+
+    Returns:
+        The updated markdown content with the new fields in frontmatter
+    """
+    existing_frontmatter = _read_frontmatter(content)
+
+    if existing_frontmatter:
+        # Parse existing frontmatter and add new fields
+        lines = existing_frontmatter.split("\n")
+
+        # Find the closing --- of frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                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_frontmatter = "\n".join(lines)
+            return _write_frontmatter(content, new_frontmatter)
+    else:
+        # Create new frontmatter with the provided fields
+        field_lines = [f"{key}: {value}" for key, value in fields.items()]
+        new_frontmatter = "---\n" + "\n".join(field_lines) + "\n---"
+        return _write_frontmatter(content, new_frontmatter)
+
+    return content
+
+
+def _add_thumbnail_to_markdown(
+    content: str, thumbnail: str, content_path: Path
+) -> tuple[str, bool]:
+    """Add thumbnail field to a markdown file's frontmatter.
+
+    Args:
+        content: The markdown content
+        thumbnail: The thumbnail value to add
+        content_path: Path for logging purposes
+
+    Returns:
+        Tuple of (modified_content, was_modified)
+    """
+    # Check if thumbnail is already set in frontmatter
+    frontmatter_content = _read_frontmatter(content)
+    if frontmatter_content and "thumbnail:" in frontmatter_content:
+        return content, False
+
+    # Add thumbnail using the fields parameter
+    modified_content = _add_fields_to_frontmatter(
+        content, 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 modified_content, True
+
+
+def build_markdown():
+    """Build markdown files for all content types"""
+    from afterpython.tools._afterpython import get_default_thumbnail
+
+    for content_type in CONTENT_TYPES:
+        # Skip doc content type - docs don't need default thumbnails
+        if content_type == "doc":
+            continue
+
+        click.echo(f"Building markdown files for {content_type}/...")
+
+        path = ap.paths.afterpython_path / content_type.lower()
+
+        # Iterate over all .md files
+        for markdown_path in path.rglob("*.md"):
+            # Skip files in _build directory
+            if "_build" in markdown_path.parts:
+                continue
+
+            # Get path relative to afterpython/
+            content_path = markdown_path.relative_to(ap.paths.afterpython_path)
+
+            # Get default thumbnail for this content type
+            default_thumbnail = get_default_thumbnail(content_type, markdown_path)
+
+            # Read the markdown file
+            content = _read_markdown(markdown_path, content_path)
+            if content is None:
+                continue
+
+            # Ensure blank line after frontmatter (fixes existing files)
+            original_content = content
+            content = _ensure_blank_line_after_frontmatter(content)
+            blank_line_added = content != original_content
+
+            # Add thumbnail to frontmatter
+            modified_content, was_modified = _add_thumbnail_to_markdown(
+                content, default_thumbnail, content_path
+            )
+
+            # Write back if modified (either blank line or thumbnail)
+            if was_modified or blank_line_added:
+                _write_markdown(modified_content, markdown_path)

afterpython/builders/metadata.py

@@ -7,6 +7,8 @@ if TYPE_CHECKING:
 
 import json
 
+import click
+
 import afterpython as ap
 
 build_path = ap.paths.build_path
@@ -30,13 +32,15 @@ def convert_paths():
     with open(build_path / "metadata.json", "w") as f:
         json.dump(metadata, f, indent=2)
 
-    print("Completed path conversion in metadata.json")
+    click.echo("Completed path conversion in metadata.json")
 
 
 def build_metadata():
     """Build metadata.json using pyproject.toml"""
     from afterpython.tools.pyproject import read_metadata
 
+    click.echo("Building metadata.json...")
+
     metadata: StandardMetadata = read_metadata()
 
     # Write to metadata.json

afterpython/cli/commands/build.py

@@ -8,7 +8,6 @@ if TYPE_CHECKING:
 
     from afterpython._typing import NodeEnv
 
-import os
 import shutil
 import subprocess
 
@@ -17,11 +16,14 @@ from click.exceptions import Exit
 
 import afterpython as ap
 from afterpython.builders import (
-    add_molab_badge_to_jupyter_notebooks,
+    build_content_json,
+    build_jupyter_notebooks,
+    build_markdown,
     build_metadata,
+    create_placeholder_index_md_files,
+    delete_placeholder_index_md_files,
 )
 from afterpython.const import CONTENT_TYPES
-from afterpython.utils import find_node_env
 
 
 def determine_base_path() -> str:
@@ -69,22 +71,31 @@ def prebuild():
                 "Run 'ap init' first to set up your project."
             )
 
-    def _clean_build_directory():
-        print("Cleaning up build directory...")
+    def _clean_up_builds():
+        click.echo("Cleaning up builds...")
         build_path = ap.paths.build_path
-        if build_path.exists():
-            shutil.rmtree(build_path)
+        website_build_path = ap.paths.website_path / "build"
+        # clean up content builds in _website/static/{content_type}
+        website_static_path = ap.paths.website_path / "static"
+        content_build_paths = [
+            website_static_path / content_type for content_type in CONTENT_TYPES
+        ]
+        for path in [build_path, website_build_path, *content_build_paths]:
+            if path.exists():
+                shutil.rmtree(path)
         build_path.mkdir(parents=True, exist_ok=True)
 
     _check_initialized()
-    _clean_build_directory()
+    _clean_up_builds()
 
-    if os.getenv("AP_MOLAB_BADGE", "1") == "1":
-        for content_type in CONTENT_TYPES:
-            add_molab_badge_to_jupyter_notebooks(content_type)
+    delete_placeholder_index_md_files()
+    create_placeholder_index_md_files()
+    build_metadata()
+    build_markdown()
+    build_jupyter_notebooks()
 
 
-def postbuild():
+def postbuild(dev_build: bool = False):
     def _move_files(
         source: Path,
         destination: Path,
@@ -112,6 +123,9 @@ def postbuild():
             shutil.move(str(source), str(destination))
             print(f"Moved: {source} to {destination}")
 
+    build_content_json()
+    delete_placeholder_index_md_files()
+
     website_static = ap.paths.website_path / "static"
     website_static.mkdir(parents=True, exist_ok=True)
 
@@ -119,15 +133,24 @@ def postbuild():
         myst_build = ap.paths.afterpython_path / content_type / "_build"
         afterpython_content_build = ap.paths.build_path / content_type
         # Move myst builds from afterpython/{content_type}/_build to afterpython/_build/{content_type}
-        _move_files(myst_build, afterpython_content_build, is_copy=False)
-        # Copy afterpython/_build/{content_type}/html to afterpython/_website/static/{content_type}
-        _move_files(
-            afterpython_content_build / "html",
-            website_static / content_type,
-            is_copy=True,
-        )
+        _move_files(myst_build, afterpython_content_build, is_copy=True)
+        # for production build, copy afterpython/_build/{content_type}/html to afterpython/_website/static/{content_type}
+        if not dev_build:
+            _move_files(
+                afterpython_content_build / "html",
+                website_static / content_type,
+                is_copy=True,
+            )
+        # for dev build, copy the files (mainly images, e.g. thumbnails) in site/public/ to afterpython/_website/static/{content_type}/build
+        else:
+            _move_files(
+                afterpython_content_build / "site" / "public",
+                # add build/ to mimic the structure of the production build
+                website_static / content_type / "build",
+                is_copy=True,
+            )
 
-    # Copy all files from afterpython/_build to afterpython/_website/static/
+    # Copy all files (e.g. metadata.json, blog.json etc.) from afterpython/_build to afterpython/_website/static/
     _move_files(
         ap.paths.build_path,
         website_static,
@@ -150,16 +173,10 @@ def postbuild():
     ),
 )
 @click.pass_context
-@click.option(
-    "--dev",
-    is_flag=True,
-    hidden=True,  # Internal flag used by `ap dev`, not exposed to users
-    help="Development build - only build metadata for the landing page, skip content and production builds",
-)
 @click.option(
     "--execute", is_flag=True, help="Execute Jupyter notebooks for all content types"
 )
-def build(ctx, dev: bool, execute: bool):
+def build(ctx: click.Context, execute: bool):
     """Build the project website and all contents for production.
 
     This command builds MyST content (doc/blog/tutorial/example/guide) and the SvelteKit website.
@@ -169,7 +186,11 @@ def build(ctx, dev: bool, execute: bool):
 
     Use --execute to execute Jupyter notebooks for all content types.
     """
-    from afterpython.utils import handle_passthrough_help, has_content_for_myst
+    from afterpython.utils import (
+        find_node_env,
+        handle_passthrough_help,
+        has_content_for_myst,
+    )
 
     # Show both our options and myst's help and exit
     handle_passthrough_help(
@@ -187,46 +208,53 @@ def build(ctx, dev: bool, execute: bool):
         click.echo(f"Using BASE_PATH: {base_path}")
     else:
         click.echo("Using BASE_PATH: (empty - custom domain)")
-
-    click.echo("Building metadata.json...")
-    build_metadata()
+    node_env: NodeEnv = find_node_env()
 
     # myst's production build
-    if not dev:
-        node_env: NodeEnv = find_node_env()
-        for content_type in CONTENT_TYPES:
-            content_path = paths.afterpython_path / content_type
-            if not has_content_for_myst(content_path):
-                click.echo(f"Skipping {content_type}/ (no content files found)")
-                continue
-
-            click.echo(f"Building {content_type}/...")
-            # NOTE: needs to set BASE_URL so that the project website can link to the content pages correctly at e.g. localhost:5173/doc
-            base_url = f"{base_path}/{content_type}"
-            build_env = {**node_env, "BASE_URL": base_url, "BASE_PATH": base_path}
-            result = subprocess.run(
-                [
-                    "myst",
-                    "build",
-                    "--html",
-                    *(["--execute"] if execute else []),
-                    *ctx.args,
-                ],
-                cwd=content_path,
-                env=build_env,
-                check=False,
+    for content_type in CONTENT_TYPES:
+        content_path = ap.paths.afterpython_path / content_type
+        myst_yml_path = content_path / "myst.yml"
+
+        if not content_path.exists():
+            click.echo(f"{content_path} does not exist, skip building {content_type}/")
+            continue
+
+        if not myst_yml_path.exists():
+            click.echo(
+                f"No myst.yml found in {content_path}, skip building {content_type}/"
             )
-            if result.returncode != 0:
-                raise Exit(result.returncode)
+            continue
 
-    postbuild()
+        if not has_content_for_myst(content_path):
+            click.echo(f"Skipping {content_type}/ (no content files found)")
+            continue
 
-    # website's production build
-    if not dev:
-        click.echo("Building project website...")
-        website_env = {**node_env, "BASE_PATH": base_path}
+        click.echo(f"Building {content_type}/...")
+        # NOTE: needs to set BASE_URL (used by MyST) so that the project website can link to the content pages correctly at e.g. localhost:5173/doc
+        base_url = f"{base_path}/{content_type}"
+        build_env = {**node_env, "BASE_URL": base_url, "BASE_PATH": base_path}
         result = subprocess.run(
-            ["pnpm", "build"], cwd=paths.website_path, env=website_env, check=False
+            [
+                "myst",
+                "build",
+                "--html",
+                *(["--execute"] if execute else []),
+                *ctx.args,
+            ],
+            cwd=content_path,
+            env=build_env,
+            check=False,
         )
+
         if result.returncode != 0:
             raise Exit(result.returncode)
+
+    postbuild(dev_build=False)
+
+    click.echo("Building project website...")
+    website_env = {**node_env, "BASE_PATH": base_path}
+    result = subprocess.run(
+        ["pnpm", "build"], cwd=paths.website_path, env=website_env, check=False
+    )
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/check.py

@@ -13,7 +13,7 @@ from click.exceptions import Exit
 )
 @click.pass_context
 def check(ctx):
-    """Simple wrapper for ruff check for convenience, always use the afterpython/ruff.toml if it exists"""
+    """Run ruff linter (uses afterpython/ruff.toml if available)"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and ruff's help and exit

afterpython/cli/commands/clean.py

@@ -26,10 +26,10 @@ from afterpython.utils import find_node_env, has_content_for_myst
 @click.option(
     "--all",
     is_flag=True,
-    help='--all passed to "myst clean", also clean afterpython build directories (_build/ and _website/build/)',
+    help="Also clean AfterPython build directories (_build/ and _website/build/)",
 )
 def clean(ctx, all: bool):
-    """Clean the build directory"""
+    """Clean build artifacts from content types and website"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and myst's help and exit

afterpython/cli/commands/commit.py

@@ -13,7 +13,10 @@ import click
 )
 @click.pass_context
 @click.option(
-    "--no-cz", "--no-commitizen", is_flag=True, help="Skip running 'cz commit'"
+    "--no-cz",
+    "--no-commitizen",
+    is_flag=True,
+    help="Skip 'commitizen' and 'commitizen-branch' pre-commit hooks",
 )
 @click.option(
     "--no-pc",
@@ -22,7 +25,7 @@ import click
     help="Skip running pre-commit checks before commit",
 )
 def commit(ctx, no_cz: bool, no_pc: bool):
-    """Run 'cz commit'"""
+    """Create a conventional commit with interactive prompts"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and commitizen's help and exit

afterpython/cli/commands/commitizen.py

@@ -13,7 +13,7 @@ from click.exceptions import Exit
 )
 @click.pass_context
 def commitizen(ctx):
-    """Run commitizen"""
+    """Run commitizen CLI (uses afterpython/cz.toml)"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and commitizen's help and exit

afterpython/cli/commands/dev.py

@@ -11,6 +11,7 @@ import time
 import click
 from click.exceptions import Exit
 
+from afterpython.cli.commands.build import postbuild, prebuild
 from afterpython.const import CONTENT_TYPES
 from afterpython.utils import find_available_port, find_node_env
 
@@ -107,9 +108,6 @@ def dev(
 
     paths = ctx.obj["paths"]
 
-    # OPTIMIZE: should implement incremental build?
-    subprocess.run(["ap", "build", "--dev"])
-
     def cleanup_processes():
         """Clean up all MyST server processes"""
         click.echo("\nShutting down MyST servers...")
@@ -140,11 +138,14 @@ def dev(
         enabled_content_types = {ct for ct, flag in content_flags.items() if flag}
 
     try:
-        if enabled_content_types:
-            # Clear .env.development before writing new ports
-            env_file = paths.website_path / ".env.development"
-            env_file.write_text("")  # Clear existing content
+        prebuild()
+
+        # Clear .env.development before writing new ports
+        env_file = paths.website_path / ".env.development"
+        env_file.write_text("")  # Clear existing content
 
+        # myst development servers
+        if enabled_content_types:
             next_port = 3000
             for content_type in CONTENT_TYPES:
                 # Skip content types that are not enabled
@@ -186,6 +187,8 @@ def dev(
                 # causing "address already in use" errors.
                 time.sleep(3)
 
+        postbuild(dev_build=True)
+
         if not no_website:
             node_env: NodeEnv = find_node_env()
             click.echo("Running the web dev server...")

afterpython/cli/commands/format.py

@@ -13,7 +13,7 @@ from click.exceptions import Exit
 )
 @click.pass_context
 def format(ctx):
-    """Simple wrapper for ruff format for convenience"""
+    """Run ruff formatter"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and ruff's help and exit

afterpython/cli/commands/init.py

@@ -48,7 +48,7 @@ def init_py_typed():
 )
 @click.pass_context
 def init(ctx, yes):
-    """Initialize afterpython with MyST Markdown (by default) and project website template"""
+    """Initialize AfterPython project structure and website template"""
     from afterpython.tools._afterpython import init_afterpython
     from afterpython.tools.commitizen import init_commitizen
     from afterpython.tools.github_actions import (

afterpython/cli/commands/install.py

@@ -13,7 +13,7 @@ from afterpython.utils import has_pixi, has_uv
     )
 )
 def install():
-    """Install all dependencies (runs 'uv sync --all-extras --all-groups' and 'pixi install' if present)"""
+    """Install all project dependencies (manages both uv and pixi if present)"""
     if not has_uv():
         click.echo("uv not found. Please install uv first.")
         return

afterpython/cli/commands/lock.py

@@ -8,7 +8,7 @@ from afterpython.utils import has_pixi, has_uv
 
 @click.command()
 def lock():
-    """Lock the dependencies (runs 'uv lock' and 'pixi lock' if present)"""
+    """Lock project dependencies (manages both uv and pixi if present)"""
     if not has_uv():
         click.echo("uv not found. Please install uv first.")
         return

afterpython/cli/commands/pre_commit.py

@@ -27,7 +27,7 @@ def _command_supports_config(command: str) -> bool:
 )
 @click.pass_context
 def pre_commit(ctx):
-    """Run pre-commit, always use the afterpython/.pre-commit-config.yaml if it exists"""
+    """Run pre-commit hooks (uses afterpython/.pre-commit-config.yaml if available)"""
     from afterpython.utils import handle_passthrough_help
 
     # Show both our options and pre-commit's help and exit