diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90374a2..5801706 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,8 +42,7 @@ Please make sure you follow the EasyScience organization-wide If you are not planning to contribute code, you may want to: - 🐞 Report a bug — see [Reporting Issues](#11-reporting-issues) -- 🛡 Report a security issue — see - [Security Issues](#12-security-issues) +- 🛡 Report a security issue — see [Security Issues](#12-security-issues) - 💬 Ask a question or start a discussion at [Project Discussions](https://github.com/easyscience/templates/discussions) diff --git a/pixi.toml b/pixi.toml index 45b11ea..300a54c 100644 --- a/pixi.toml +++ b/pixi.toml @@ -161,8 +161,9 @@ docs-serve = 'pixi run docs-pre serve -f docs/mkdocs.yml' docs-serve-dirty = 'pixi run docs-serve --dirty' docs-build = 'pixi run docs-pre build -f docs/mkdocs.yml' docs-build-local = 'pixi run docs-build --no-directory-urls' +docs-inventory-check = 'python -c "from pathlib import Path; p = Path(\"docs/site/objects.inv\"); raise SystemExit(0 if p.is_file() and p.stat().st_size > 0 else \"missing or empty docs/site/objects.inv\")"' -docs-deploy-pre = 'mike deploy -F docs/mkdocs.yml --push --branch gh-pages --update-aliases --alias-type redirect' +docs-deploy-pre = 'mike deploy -F docs/mkdocs.yml --push --branch gh-pages --update-aliases --alias-type copy' docs-set-default-pre = 'mike set-default -F docs/mkdocs.yml --push --branch gh-pages' docs-update-assets = 'python tools/update_docs_assets.py' diff --git a/template/.github/workflows/docs.yml.jinja b/template/.github/workflows/docs.yml.jinja index 43697d8..95866de 100644 --- a/template/.github/workflows/docs.yml.jinja +++ b/template/.github/workflows/docs.yml.jinja @@ -126,11 +126,14 @@ jobs: # Build the static files for the documentation site for local inspection # Input: docs/ directory containing the Markdown files - # Output: site/ directory containing the generated HTML files + # Output: docs/site/ directory containing the generated HTML files + # Also verifies that mkdocstrings generated docs/site/objects.inv. - name: Build site for local check - run: pixi run docs-build-local + run: | + pixi run docs-build-local + pixi run docs-inventory-check - # Upload the static files from the site/ directory to be used for + # Upload the static files from the docs/site/ directory to be used for # local check - name: Upload built site as artifact uses: ./.github/actions/upload-artifact diff --git a/template/docs/mkdocs.yml.jinja b/template/docs/mkdocs.yml.jinja index 6c8d966..af3a820 100644 --- a/template/docs/mkdocs.yml.jinja +++ b/template/docs/mkdocs.yml.jinja @@ -182,6 +182,13 @@ plugins: docstring_options: ignore_init_summary: true summary: true + relative_crossrefs: true + scoped_crossrefs: true + filters: ["!^_[^_]", "!__repr__", "!__dir__"] # This is the default filter minus __repr__ and __dir__ + inventories: + - url: https://scipp.github.io/objects.inv + - url: https://numpy.org/doc/stable/objects.inv + - url: https://easyscience.github.io/core/latest/objects.inv - search # Determines additional directories to watch when running mkdocs serve diff --git a/template/pixi.toml.jinja b/template/pixi.toml.jinja index dc1ac83..a6b04b4 100644 --- a/template/pixi.toml.jinja +++ b/template/pixi.toml.jinja @@ -214,8 +214,9 @@ docs-serve = 'pixi run docs-pre serve -f docs/mkdocs.yml' docs-serve-dirty = 'pixi run docs-serve --dirty' docs-build = 'pixi run docs-pre build -f docs/mkdocs.yml' docs-build-local = 'pixi run docs-build --no-directory-urls' +docs-inventory-check = 'python -c "from pathlib import Path; p = Path(\"docs/site/objects.inv\"); raise SystemExit(0 if p.is_file() and p.stat().st_size > 0 else \"missing or empty docs/site/objects.inv\")"' -docs-deploy-pre = 'mike deploy -F docs/mkdocs.yml --push --branch gh-pages --update-aliases --alias-type redirect' +docs-deploy-pre = 'mike deploy -F docs/mkdocs.yml --push --branch gh-pages --update-aliases --alias-type copy' docs-set-default-pre = 'mike set-default -F docs/mkdocs.yml --push --branch gh-pages' docs-update-assets = 'python tools/update_docs_assets.py'