afterpython 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

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/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/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/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/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/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/tools/_afterpython.py

@@ -125,6 +125,7 @@ def init_afterpython():
             "thumbnail": "thumbnail.png",
             "announcement": "",
             "readme_py": "wasm",
+            "api_reference": False,
         },
     }
     update_afterpython(default_data)

{afterpython-0.3.1.dist-info → afterpython-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afterpython
-Version: 0.3.1
+Version: 0.3.2
 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.dist-info → afterpython-0.3.2.dist-info}/RECORD

@@ -3,7 +3,8 @@ afterpython/_io/toml.py,sha256=dvmq6n4MhlJ02u_YjfC3mOnCWatfCn_J1lugavigoJw,3410
 afterpython/_io/yaml.py,sha256=raksve_gaIFJim8lQrq-kQHkRjTloed7CT2FY0oUJSg,654
 afterpython/_paths.py,sha256=FTwQ7necKYuRosCyMZPfv1eqaEmGIsyqd3yXpm-WQTA,1584
 afterpython/_typing.py,sha256=FbphSGoujPuTfCZqt0HaKQrBgzhRpCOEAEQU6Cbl7oA,145
-afterpython/builders/__init__.py,sha256=FDc-mChfq7zZWbjp7qZuOnXir_H3eg2wHAMgQb2_oKw,902
+afterpython/builders/__init__.py,sha256=H7f9mFKXofWOAC3hkrxiFzvW5NziF8wYyduUBykHa5w,975
+afterpython/builders/build_pdoc.py,sha256=rasjCtTah5GsZYokqU--Fp3bvTEf464ievENfOoANOk,2040
 afterpython/builders/content_json.py,sha256=-LTkeA8oA6XEudc2b1H7U0-UwcJlHn7xgICeweMYrG0,4805
 afterpython/builders/faq_json.py,sha256=mMfFepRBL_1QYO0tQ6orf5ESo2LVntk55nfFzencViM,1193
 afterpython/builders/index_md.py,sha256=SDVHnVftL4D1AA8jw2YvRdTem_Ho8v8DcrORVjVtW8A,3762
@@ -15,8 +16,8 @@ afterpython/builders/metadata.py,sha256=mXTeEpxdwNFlaUwFYLLU1UXvSX2T-pzIxzssFdmn
 afterpython/builders/url_md.py,sha256=uuW3YCyphd-Qvl9Yopv48utu6y1tyfJHNc25sS-O6Yw,3526
 afterpython/cli/__init__.py,sha256=G4AB-rllhmr7tURFc5cXJfkjZZ2bXtMBg3oy4zUGEFw,84
 afterpython/cli/commands/add.py,sha256=Ppp4msdvOwN9_-fdG5-b0-IV9p0Eef9CiIEU3srUjYk,1792
-afterpython/cli/commands/build.py,sha256=lJgsOOZ9V2mHlVL4GzdZqClWYZIbPNsjAUobAPRacLc,10512
-afterpython/cli/commands/bump.py,sha256=2MZBQ1kxjr0bWhA--_xHwdwjsUlCyrXPn3pJ5NDZO4k,4088
+afterpython/cli/commands/build.py,sha256=h0AaZuhjuxD_2Iu_CHD-3-OMBbi-ncAYuMUIR2pha1k,11798
+afterpython/cli/commands/bump.py,sha256=9fR-wShNKhXbW2JgMExPlyI2n14TfQOtowAuALp-N-8,4122
 afterpython/cli/commands/check.py,sha256=lrPaVThAwxxnczu-VOZT7dd7aKjstnMQfX9UpZY3Lxs,1058
 afterpython/cli/commands/clean.py,sha256=havP43ZC1AKFzvscsRMF_to6TvOwruxGA5qzr6dMHvg,2529
 afterpython/cli/commands/commit.py,sha256=9QOKyt4tfTJzZEdHEPAdpUc4stYMSvG3-31uADuBxn4,1420
@@ -44,10 +45,11 @@ afterpython/templates/ci-workflow-template.yml,sha256=NSuPjSgo9l70a1IwUuasvgKk-K
 afterpython/templates/cz-template.toml,sha256=2qwbQLb0nbZaA63oWXFFzvzPNBsFZHATL1C2rdNdjjs,185
 afterpython/templates/dependabot-template.yml,sha256=CBQEgh8EsXw2X7IqzGtFI7lVT9liF6PW4DvGLB0X2LY,1136
 afterpython/templates/deploy-workflow-template.yml,sha256=L3dSB0WdUvuW2C65MqxkMNbUFCU8-eGvfS_wUj2etNU,2397
-afterpython/templates/pre-commit-config-template.yaml,sha256=u_JF4YHGHIWxLdcX5BS__VsVgOwwVQQsSZGPNR2Yyf0,915
+afterpython/templates/pdoc/frame.html.jinja2,sha256=GX4pNSuYC4Fq9hvZ01WyaBQes4FyNDOx5Ra4MNLr0eg,250
+afterpython/templates/pre-commit-config-template.yaml,sha256=FfQb0mVWouGmV62uCF5WO18hodZhGt-PfybB6m9nsAM,917
 afterpython/templates/release-workflow-template.yml,sha256=3YBkgrqmi--uznslpMxPz7Vj7L4_NPlhDxgwYBt-Ui8,1606
 afterpython/templates/ruff-template.toml,sha256=lNCd4EthoLScr4cyVEgGUH4xK5CfIX3f9I3zkJHAYgg,1008
-afterpython/tools/_afterpython.py,sha256=KsMWQLU6VTZ-0X3cLierPHxH9vbkloax9eI-aFAejR4,4309
+afterpython/tools/_afterpython.py,sha256=IgzUG8ihdaqrqLIma8yy6pVtC2ldt4jyWOf6FQWnKCU,4345
 afterpython/tools/_git.py,sha256=aO-qDEQ4OevD_B74DYKK4nQKYeiaS1BXmYc8paJRfbQ,3772
 afterpython/tools/branch_rules.py,sha256=ciQ2H2YBnoCZu_plyVeIHzf2FcAILRFhpjzOR2_IfJg,3159
 afterpython/tools/commitizen.py,sha256=ZO1qHmzUU0myd85tncv76WtIR7DB_AoQGSUvaf78Ohg,438
@@ -57,7 +59,7 @@ afterpython/tools/pre_commit.py,sha256=oNsrUkPI13rSSBSyhyTTKPnQGhDxLIPYhxu6kL0fD
 afterpython/tools/pyproject.py,sha256=hz-DOf-pkGBF2m_RqEZipAaO-NDbsLxrrc65LWAIwLA,3698
 afterpython/utils.py,sha256=fVa3jIzCvhn7QA7N0M6d_pvojpPFrN-hae8trUYhPKU,11701
 afterpython/version.py,sha256=hihRV1S-gc1m46OaXD32ikkEkqzs-Gtq7AcAqOQV-wY,1603
-afterpython-0.3.1.dist-info/WHEEL,sha256=q5IF0q2xCp3ktUFRCVWsQLjl2ChNlWXBJtnI1LCGdJ8,80
-afterpython-0.3.1.dist-info/entry_points.txt,sha256=roa0PDgBueM1JPbRG0G2OSxzaN394OUL_oS9iEwVLBc,80
-afterpython-0.3.1.dist-info/METADATA,sha256=OQnF1DZiQZxb84NLUYhQWMHSXpu68mErYGFRqFntY68,6218
-afterpython-0.3.1.dist-info/RECORD,,
+afterpython-0.3.2.dist-info/WHEEL,sha256=-unyBNsdNo6Y_XVO25zjvxasG_uUFN_fBd_kLyKE-Fk,81
+afterpython-0.3.2.dist-info/entry_points.txt,sha256=roa0PDgBueM1JPbRG0G2OSxzaN394OUL_oS9iEwVLBc,80
+afterpython-0.3.2.dist-info/METADATA,sha256=Rhe3BEDPDmJrHdwZtiNQwa6EJ71P975ErqSNeLLrerE,6181
+afterpython-0.3.2.dist-info/RECORD,,

{afterpython-0.3.1.dist-info → afterpython-0.3.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.11.8
+Generator: uv 0.11.12
 Root-Is-Purelib: true
 Tag: py3-none-any