Skip to content

Commit

Permalink
switch to mkdocstrings for API generation
Browse files Browse the repository at this point in the history
- project page: https://mkdocstrings.github.io
- add script to generate API pages
- remove doxygen
- configure reasonable API styles
- change function docstring to correct generation
  • Loading branch information
minhnh committed Nov 21, 2024
1 parent a702204 commit 0c7319c
Show file tree
Hide file tree
Showing 7 changed files with 80 additions and 25 deletions.
5 changes: 2 additions & 3 deletions .github/workflows/deploy-mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
5 changes: 0 additions & 5 deletions docs/python-pkg-tmpl/index.md

This file was deleted.

3 changes: 0 additions & 3 deletions docs/requirements.txt

This file was deleted.

36 changes: 25 additions & 11 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
38 changes: 38 additions & 0 deletions scripts/gen_api_pages.py
Original file line number Diff line number Diff line change
@@ -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())
9 changes: 6 additions & 3 deletions src/python_pkg_tmpl/tmpl_module.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

0 comments on commit 0c7319c

Please sign in to comment.