feat: add build for pypi workflow

- adds GitHub workflow to build for PyPI
- adds a convenience script to build package
- `isort`'s first-party is now annotated as `local`
- minor modifications made to `docs/gen_docs.py`

Author: nandgator

.github/workflows/build.yml

@@ -0,0 +1,42 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Build for PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      # checkout repository
+      - uses: actions/checkout@v3
+      # setup lowest supported python version
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+      # install & configure poetry
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.4.1
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+      # install dependencies
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-ansi --only docs
+      # build package
+      - name: Build package
+        run: python build.py
+      # publish package
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

build.py

@@ -0,0 +1,16 @@
+"""Remove Refs."""
+
+# standard
+from subprocess import run
+from shutil import rmtree
+from pathlib import Path
+
+# local
+from docs.gen_docs import generate_documentation
+
+if __name__ == "__main__":
+    project_dir = Path(__file__).parent
+    generate_documentation(project_dir, discard_refs=False)
+    process = run(("poetry", "build"), capture_output=True)
+    print(process.stderr.decode() + process.stdout.decode())
+    rmtree(project_dir / "docs/reference", ignore_errors=True)

docs/gen_docs.py

@@ -8,11 +8,12 @@
 from os.path import getsize
 from subprocess import run
 from pathlib import Path
-from sys import argv
 
 # external
 from yaml import safe_load, safe_dump
 
+__all__ = ("generate_documentation",)
+
 
 def _write_ref_content(source: Path, module_name: str, func_name: str):
     """Write content."""
@@ -23,7 +24,7 @@ def _write_ref_content(source: Path, module_name: str, func_name: str):
         )
 
 
-def generate_reference(source: Path, destination: Path):
+def _generate_reference(source: Path, destination: Path):
     """Generate reference."""
     nav_items: Dict[str, List[str]] = {"Code Reference": []}
     # clean destination
@@ -43,7 +44,7 @@ def generate_reference(source: Path, destination: Path):
     return nav_items
 
 
-def update_mkdocs_config(source: Path, destination: Path, nav_items: Dict[str, List[str]]):
+def _update_mkdocs_config(source: Path, destination: Path, nav_items: Dict[str, List[str]]):
     """Temporary update to mkdocs config."""
     copy(source, destination)
     with open(source, "rt") as mkf:
@@ -53,25 +54,27 @@ def update_mkdocs_config(source: Path, destination: Path, nav_items: Dict[str, L
         safe_dump(mkdocs_conf, mkf, sort_keys=False)
 
 
-def generate_documentation(source: Path):
+def generate_documentation(source: Path, discard_refs: bool = True):
     """Generate documentation."""
     # copy readme as docs index file
     copy(source / "README.md", source / "docs/index.md")
     # generate reference documentation
-    nav_items = generate_reference(source / "validators/__init__.py", source / "docs/reference")
+    nav_items = _generate_reference(source / "validators/__init__.py", source / "docs/reference")
     # backup mkdocs config
-    update_mkdocs_config(source / "mkdocs.yml", source / "mkdocs.bak.yml", nav_items)
+    _update_mkdocs_config(source / "mkdocs.yml", source / "mkdocs.bak.yml", nav_items)
     # build docs as subprocess
     print(run(("mkdocs", "build"), capture_output=True).stderr.decode())
     # restore mkdocs config
     move(str(source / "mkdocs.bak.yml"), source / "mkdocs.yml")
+    # optionally discard reference folder
+    if discard_refs:
+        rmtree(source / "docs/reference")
 
 
 if __name__ == "__main__":
-    project_dir = Path(__file__).parent.parent
-    generate_documentation(project_dir)
-    # use this option before building package
-    # with `poetry build` to include refs
-    if len(argv) > 1 and argv[1] == "--keep":
-        quit()
-    rmtree(project_dir / "docs/reference")
+    project_root = Path(__file__).parent.parent
+    generate_documentation(project_root)
+    # NOTE: use following lines only for testing/debugging
+    # generate_documentation(project_root, discard_refs=False)
+    # from sys import argv
+    # generate_documentation(project_root, len(argv) > 1 and argv[1] == "--keep")

pyproject.toml

@@ -71,6 +71,7 @@ exclude_dirs = [".github", ".pytest_cache", ".tox", ".vscode", "site", "tests"]
 ensure_newline_before_comments = true
 force_grid_wrap = 0
 force_sort_within_sections = true
+import_heading_firstparty = "local"
 import_heading_localfolder = "local"
 import_heading_stdlib = "standard"
 import_heading_thirdparty = "external"