From e612c6ecddf915d19b8c16e2681ed99229394fe7 Mon Sep 17 00:00:00 2001 From: Jovial Joe Jayarson Date: Thu, 23 Mar 2023 16:53:07 +0530 Subject: [PATCH] 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` --- .github/workflows/build.yml | 42 +++++++++++++++++++++++++++++++++++++ build.py | 16 ++++++++++++++ docs/gen_docs.py | 29 +++++++++++++------------ pyproject.toml | 1 + 4 files changed, 75 insertions(+), 13 deletions(-) create mode 100644 .github/workflows/build.yml create mode 100644 build.py diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 00000000..eb41de11 --- /dev/null +++ b/.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 }} diff --git a/build.py b/build.py new file mode 100644 index 00000000..01a0b41d --- /dev/null +++ b/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) diff --git a/docs/gen_docs.py b/docs/gen_docs.py index fdb5e2b7..31cc3359 100644 --- a/docs/gen_docs.py +++ b/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") diff --git a/pyproject.toml b/pyproject.toml index 7ccbfdab..312445c9 100644 --- a/pyproject.toml +++ b/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"