afterpython 0.3.1__tar.gz → 0.3.3__tar.gz

{afterpython-0.3.1 → afterpython-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afterpython
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -19,12 +19,12 @@ Requires-Dist: trogon>=0.6.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: tomlkit>=0.14.0
 Requires-Dist: ruamel-yaml>=0.19.1
-Requires-Dist: gitpython>=3.1.49
+Requires-Dist: gitpython>=3.1.50
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: pyproject-metadata>=0.11.0
 Requires-Dist: jupytext>=1.19.1
 Requires-Dist: mystmd>=1.9.0
-Requires-Dist: great-docs>=0.9
+Requires-Dist: pdoc>=16.0.0
 Requires-Dist: ruff>=0.15.12
 Requires-Dist: pre-commit>=4.6.0
 Requires-Dist: commitizen>=4.13.10
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
 [pre-commit]: https://pre-commit.com
 [pagefind]: https://pagefind.app
 [SemVer]: https://semver.org
-[great-docs]: https://posit-dev.github.io/great-docs/
+[pdoc]: https://pdoc.dev/
 [GitHub Actions]: https://github.com/features/actions
 [PyTorch]: https://pytorch.org
 [Scikit-Learn]: https://scikit-learn.org
@@ -124,7 +124,7 @@ ap tui
 - [project-website-template]
 - [pre-commit]
 - [GitHub Actions]
-- [great-docs]
+- [pdoc]
 - [commitizen]
 - [uv]
 - [ruff]

{afterpython-0.3.1 → afterpython-0.3.3}/README.md

@@ -17,7 +17,7 @@
 [pre-commit]: https://pre-commit.com
 [pagefind]: https://pagefind.app
 [SemVer]: https://semver.org
-[great-docs]: https://posit-dev.github.io/great-docs/
+[pdoc]: https://pdoc.dev/
 [GitHub Actions]: https://github.com/features/actions
 [PyTorch]: https://pytorch.org
 [Scikit-Learn]: https://scikit-learn.org
@@ -88,7 +88,7 @@ ap tui
 - [project-website-template]
 - [pre-commit]
 - [GitHub Actions]
-- [great-docs]
+- [pdoc]
 - [commitizen]
 - [uv]
 - [ruff]

{afterpython-0.3.1 → afterpython-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "afterpython"
-version = "0.3.1"
+version = "0.3.3"
 description = "CLI tool to streamline Python package maintenance and generate a dedicated project website"
 license = "Apache-2.0"
 authors = [
@@ -37,14 +37,14 @@ dependencies = [
     "httpx>=0.28.1",
     "tomlkit>=0.14.0",
     "ruamel-yaml>=0.19.1",
-    "gitpython>=3.1.49",
+    "gitpython>=3.1.50",
     # "pygithub>=2.8.1",
     "python-dotenv>=1.2.2",
     "pyproject-metadata>=0.11.0",
     "jupytext>=1.19.1",
     # "jinja2>=3.1.6",
     "mystmd>=1.9.0",
-    "great-docs>=0.9",
+    "pdoc>=16.0.0",
     "ruff>=0.15.12",
     "pre-commit>=4.6.0",
     "commitizen>=4.13.10",
@@ -64,7 +64,7 @@ pcu = "afterpython.main:run_pcu"
 # override-dependencies = ["platformdirs>=4.5.0", "nodeenv>=1.9.1"]
 
 [build-system]
-requires = ["uv_build>=0.11.8,<0.12.0"]
+requires = ["uv_build>=0.11.12,<0.12.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/builders/__init__.py

@@ -1,3 +1,4 @@
+from afterpython.builders.build_pdoc import build_pdoc
 from afterpython.builders.content_json import build_content_json
 from afterpython.builders.faq_json import build_faq_json
 from afterpython.builders.index_md import (
@@ -19,6 +20,7 @@ __all__ = (
     "build_marimo_readme",
     "build_markdown",
     "build_metadata",
+    "build_pdoc",
     "build_url_md",
     "create_placeholder_index_md_files",
     "delete_placeholder_index_md_files",

afterpython-0.3.3/src/afterpython/builders/build_pdoc.py

@@ -0,0 +1,57 @@
+import os
+import subprocess
+
+import click
+
+import afterpython as ap
+from afterpython.tools.pyproject import find_package_directory
+
+
+def build_pdoc(base_path: str) -> None:
+    """Generate API reference HTML from the user's package via pdoc.
+
+    Output goes to `_build/api_reference/` (the standard staging dir);
+    the build command is responsible for copying it into the website's
+    static dir.
+
+    `base_path` is "" for custom domains and "/{repo-name}" for GitHub
+    Pages — used to wire pdoc's logo + logo-link flags so that the
+    project logo appears in the top-left of every API page and links
+    back to the project website root (matches MyST's UX).
+    """
+    package_dir = find_package_directory()
+    output_dir = ap.paths.build_path / "api_reference"
+    template_dir = ap.paths.templates_path / "pdoc"
+
+    click.echo("Building api_reference/...")
+
+    # PDOC_ALLOW_EXEC=1 lets module-level subprocess calls run during pdoc's
+    # introspection import. Required because some deps (e.g. jupytext) shell
+    # out to `pandoc --version` at import time. Safe here: pdoc imports the
+    # user's own package, whose import-time behavior the user already trusts.
+    env = {**os.environ, "PDOC_ALLOW_EXEC": "1"}
+
+    # logo.svg is a project-website-template convention (always present in
+    # `_website/static/`); served at `{base_path}/logo.svg` once the site
+    # is built. logo-link points back to the project website root.
+    result = subprocess.run(
+        [
+            "pdoc",
+            "-o",
+            str(output_dir),
+            "--logo",
+            f"{base_path}/logo.svg",
+            "--logo-link",
+            f"{base_path}/",
+            "--template-directory",
+            str(template_dir),
+            str(package_dir),
+        ],
+        env=env,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"pdoc failed with exit code {result.returncode}. "
+            f"Re-run `ap build --skip-api` to skip API reference generation."
+        )

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/cli/commands/build.py

@@ -24,6 +24,7 @@ from afterpython.builders import (
     build_marimo_readme,
     build_markdown,
     build_metadata,
+    build_pdoc,
     build_url_md,
     create_placeholder_index_md_files,
     delete_placeholder_index_md_files,
@@ -66,6 +67,22 @@ def determine_base_path() -> str:
     return f"/{repo_name}"
 
 
+def _read_api_reference() -> bool:
+    """Read `[website].api_reference` from afterpython.toml. Defaults to False.
+
+    Off-by-default means freshly `ap init`'d projects don't blow up on
+    `ap build` before their package is import-ready or has docstrings —
+    pdoc errors are opt-in surface. Users enable the API reference by
+    setting the field to true.
+    """
+    from afterpython._io.toml import _from_tomlkit
+    from afterpython.tools._afterpython import read_afterpython
+
+    afterpython = read_afterpython()
+    website = _from_tomlkit(afterpython.get("website", {}))
+    return bool(website.get("api_reference", False))
+
+
 def prebuild():
     def _check_initialized():
         # Check if 'ap init' has been run
@@ -85,7 +102,15 @@ def prebuild():
         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]:
+        # Also wipe the API reference static dir so a `--skip-api` build doesn't
+        # leave stale pages from a prior run live on the deployed site.
+        api_static_path = website_static_path / "api_reference"
+        for path in [
+            build_path,
+            website_build_path,
+            api_static_path,
+            *content_build_paths,
+        ]:
             if path.exists():
                 shutil.rmtree(path)
         build_path.mkdir(parents=True, exist_ok=True)
@@ -209,7 +234,11 @@ def postbuild(dev_build: bool = False):
 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.
+    This command builds MyST content (doc/blog/tutorial/example/guide), the API
+    reference (via pdoc), and the SvelteKit website.
+
+    The API reference is opt-in via `[website].api_reference = true` in
+    afterpython.toml — by default it is skipped.
 
     Any extra arguments are passed to the 'myst build --html' command for each content type.
     See "myst build --help" for more details.
@@ -240,12 +269,18 @@ def build(ctx: click.Context, execute: bool):
     paths = ctx.obj["paths"]
     prebuild()
 
-    # Determine BASE_PATH based on website URL configuration
+    # Determine BASE_PATH based on website URL configuration. Computed
+    # before build_pdoc() so it can wire pdoc's logo-link back to the
+    # project website root.
     base_path = determine_base_path()
     if base_path:
         click.echo(f"Using BASE_PATH: {base_path}")
     else:
         click.echo("Using BASE_PATH: (empty - custom domain)")
+
+    if _read_api_reference():
+        build_pdoc(base_path=base_path)
+
     node_env: NodeEnv = find_node_env()
 
     # myst's production build

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/cli/commands/bump.py

@@ -75,7 +75,7 @@ def bump(ctx, release: bool, pre: bool):
 
         # by default, bump dev-release version
         if version.is_devrelease and not pre:
-            devrelease_number = int(version.dev)
+            devrelease_number = int(version.dev) if version.dev is not None else 0
             if "--devrelease" not in ctx.args:
                 args = ["--devrelease", str(devrelease_number + 1), *ctx.args]
         # exclude e.g. 0.1.0.dev1 which is both dev-release and pre-release (with version.pre = None)

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/cli/commands/update.py

@@ -251,7 +251,10 @@ def website(ctx, no_backup: bool):
         ensure_website_gitignore_rules()
     except Exception as e:
         click.echo(f"✗ Error updating project website template: {e}", err=True)
-        if not no_backup:
+        # On a fresh `ap init`, website_path didn't exist beforehand, so no backup
+        # was created — skip restore in that case rather than crashing with
+        # FileNotFoundError, which would mask the real error above.
+        if not no_backup and backup_path.exists():
             click.echo("Restoring from backup...")
             if website_path.exists():
                 shutil.rmtree(website_path)

afterpython-0.3.3/src/afterpython/templates/pdoc/frame.html.jinja2

@@ -0,0 +1,7 @@
+{% extends "default/frame.html.jinja2" %}
+{# Override pdoc's default 35vh logo height — too dominant in the sidebar. #}
+{% block head %}
+    <style>
+        nav.pdoc img.logo { max-height: 5rem; margin-bottom: 1.5rem; }
+    </style>
+{% endblock %}

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/templates/pre-commit-config-template.yaml

@@ -23,7 +23,7 @@ repos:
     stages:
     - pre-commit
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.14.8
+  rev: v0.15.12
   hooks:
   - id: ruff-check
     stages:
@@ -38,7 +38,7 @@ repos:
     - --config
     - ./afterpython/ruff.toml
 - repo: https://github.com/commitizen-tools/commitizen
-  rev: v4.10.0
+  rev: v4.13.10
   hooks:
   - id: commitizen
     stages:

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/tools/_afterpython.py

@@ -119,12 +119,13 @@ def init_afterpython():
         },
         "website": {
             "url": "",
-            "favicon": "favicon.svg",
+            "favicon": "favicon.ico",
             "logo": "logo.svg",
             "logo_dark": "logo.svg",
             "thumbnail": "thumbnail.png",
             "announcement": "",
             "readme_py": "wasm",
+            "api_reference": False,
         },
     }
     update_afterpython(default_data)

{afterpython-0.3.1 → afterpython-0.3.3}/src/afterpython/tools/myst.py

@@ -182,7 +182,9 @@ def init_myst():
 
     # find any existing node.js version and use it, if no, install the Node.js version specified in NODEENV_VERSION
     node_env: NodeEnv = find_node_env()
-    subprocess.run(["npm", "install", "-g", "pnpm"], env=node_env, check=True)
+    # Pin to pnpm major version — `npm install -g pnpm` (unpinned) caused a
+    # silent 9→10 jump that broke `ap init` via ERR_PNPM_IGNORED_BUILDS.
+    subprocess.run(["npm", "install", "-g", "pnpm@11"], env=node_env, check=True)
     for content_type in CONTENT_TYPES:
         path = ap.paths.afterpython_path / content_type
         print(f"Initializing MyST Markdown (mystmd) in {path.name}/ directory ...")