diff --git a/.github/workflows/deploy-mkdocs.yml b/.github/workflows/deploy-mkdocs.yml new file mode 100644 index 0000000..954f553 --- /dev/null +++ b/.github/workflows/deploy-mkdocs.yml @@ -0,0 +1,23 @@ +name: Publish docs with MkDocs via GitHub Pages +on: + push: + branches: + - main + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install ".[docs]" + - name: Deploy MkDocs + run: mkdocs gh-deploy --force diff --git a/README.md b/README.md index 97a33b3..553c708 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Common installation patterns: - Install with optional dependencies (as specified in [`pyproject.toml`](./pyproject.toml), here `test`): `pip install ".[test]"` -Note: double quote is needed in `zsh` to avoid "no matches" error. +> **_NOTE:_** double quote is needed in `zsh` to avoid "no matches" error. ## Linting diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/styles/extra.css b/docs/styles/extra.css new file mode 100644 index 0000000..e9c04d2 --- /dev/null +++ b/docs/styles/extra.css @@ -0,0 +1,6 @@ +:root { + --md-primary-fg-color: #9d2246; + --md-primary-fg-color--light: #d50c2f; + --md-primary-fg-color--dark: #9d2246; + --md-accent-fg-color: #f39ca9; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ab00744 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,77 @@ +site_name: Template Python Package +site_description: 'A template Python Package for SECORO AG at Bremen University' +site_author: 'SECORO AG' +repo_url: https://github.com/secorolab/python-pkg-template + +nav: + - Home: index.md + # defer to gen-files + literate-nav + - API reference: reference/ +theme: + name: 'material' + # logo: assets/logo.png + icon: + repo: fontawesome/brands/github + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + primary: custom + accent: custom + toggle: + icon: material/brightness-auto + name: Switch to light mode + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: custom + accent: custom + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: custom + accent: custom + toggle: + icon: material/brightness-4 + name: Switch to system preference + +plugins: + - search + - awesome-pages + - 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 + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/secorolab + - icon: material/web + link: https://www.uni-bremen.de/secoro + +copyright: Copyright © 2024 SECORO Group 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)