From 0c7319cc857b01e2eaaa65fa37f2961d0c40569c Mon Sep 17 00:00:00 2001 From: Minh Nguyen Date: Thu, 21 Nov 2024 16:10:35 +0100 Subject: [PATCH] switch to mkdocstrings for API generation - project page: https://mkdocstrings.github.io - add script to generate API pages - remove doxygen - configure reasonable API styles - change function docstring to correct generation --- .github/workflows/deploy-mkdocs.yml | 5 ++-- docs/python-pkg-tmpl/index.md | 5 ---- docs/requirements.txt | 3 --- mkdocs.yml | 36 ++++++++++++++++++--------- pyproject.toml | 9 +++++++ scripts/gen_api_pages.py | 38 +++++++++++++++++++++++++++++ src/python_pkg_tmpl/tmpl_module.py | 9 ++++--- 7 files changed, 80 insertions(+), 25 deletions(-) delete mode 100644 docs/python-pkg-tmpl/index.md delete mode 100644 docs/requirements.txt create mode 100644 scripts/gen_api_pages.py diff --git a/.github/workflows/deploy-mkdocs.yml b/.github/workflows/deploy-mkdocs.yml index b69b86f..d6bb657 100644 --- a/.github/workflows/deploy-mkdocs.yml +++ b/.github/workflows/deploy-mkdocs.yml @@ -18,8 +18,7 @@ jobs: git config user.email 41898282+github-actions[bot]@users.noreply.github.com - name: Install dependencies run: | - sudo python -m pip install --upgrade pip - sudo apt install doxygen - sudo pip install -r docs/requirements.txt + python -m pip install --upgrade pip + python -m pip install ".[docs]" - name: Deploy MkDocs run: mkdocs gh-deploy --force diff --git a/docs/python-pkg-tmpl/index.md b/docs/python-pkg-tmpl/index.md deleted file mode 100644 index 1a2cabf..0000000 --- a/docs/python-pkg-tmpl/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# API documentation for `python_pkg_tmpl` - -Documentation for `python_pkg_tmpl` is generated using [MkDoxy](https://github.com/JakubAndrysek/MkDoxy). - -Links to all API documentation are available under the [Links](./links) page. diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 80bc09f..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -mkdocs-material -mkdocs-awesome-pages-plugin -mkdoxy diff --git a/mkdocs.yml b/mkdocs.yml index 6014067..ab00744 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,9 +5,8 @@ repo_url: https://github.com/secorolab/python-pkg-template nav: - Home: index.md - - Python Package Template API: - - python-pkg-tmpl/index.md - - ... | python-pkg-tmpl/*.md + # defer to gen-files + literate-nav + - API reference: reference/ theme: name: 'material' # logo: assets/logo.png @@ -41,14 +40,29 @@ theme: plugins: - search - awesome-pages - - mkdoxy: - projects: - python-pkg-tmpl: - src-dirs: src/python_pkg_tmpl - full-doc: True - doxy-cfg: - FILE_PATTERNS: "*.py" - RECURSIVE: True + - gen-files: + scripts: + - scripts/gen_api_pages.py + - literate-nav: + nav_file: SUMMARY.md + - section-index + - mkdocstrings: + default_handler: python + handlers: + python: + # cross-ref to other projects + import: + - https://docs.python.org/3/objects.inv + paths: [src] + options: + # see full list of options at https://mkdocstrings.github.io/python/usage/ + docstring_options: + ignore_init_summary: true + docstring_section_style: list + merge_init_into_class: true + separate_signature: true + heading_level: 1 + summary: true extra_css: - styles/extra.css diff --git a/pyproject.toml b/pyproject.toml index e4eb977..bc5ffe0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,6 +25,15 @@ dependencies = [ test = [ "pytest", ] +docs = [ + "pathlib", # API generation script + "mkdocs-material", # material theme + "mkdocs-awesome-pages-plugin", # allow short hands for loading all markdowns + "mkdocstrings[python]", # render API pages for Python + "mkdocs-literate-nav", # summary API page + "mkdocs-gen-files", # generate API files + "mkdocs-section-index", # generate index for API +] [project.urls] "Homepage" = "https://github.com/secorolab/python-pkg-template" diff --git a/scripts/gen_api_pages.py b/scripts/gen_api_pages.py new file mode 100644 index 0000000..d45ca7f --- /dev/null +++ b/scripts/gen_api_pages.py @@ -0,0 +1,38 @@ +"""Generate the API reference pages. + +Taken from https://mkdocstrings.github.io/recipes/ +""" + +from pathlib import Path +import mkdocs_gen_files + + +root = Path(__file__).parent.parent +src = root / "src" + +nav = mkdocs_gen_files.Nav() + +for path in sorted(src.rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = Path("reference", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"---\ntitle: {ident}\n---\n\n::: {ident}") + + mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) diff --git a/src/python_pkg_tmpl/tmpl_module.py b/src/python_pkg_tmpl/tmpl_module.py index d207749..0b8a427 100644 --- a/src/python_pkg_tmpl/tmpl_module.py +++ b/src/python_pkg_tmpl/tmpl_module.py @@ -7,9 +7,12 @@ def get_pkg_cache_dir(subdir: str = PKG_NAME) -> str: - """!Returns a subdirectory under the user's cache directory + """Returns a subdirectory under the user's cache directory - @param subdir subdirectory name - @return path to subdir in the user's cache directory + Parameters: + subdir: subdirectory name + + Returns: + path to subdir in the user's cache directory """ return join(user_cache_dir(), subdir)