Improve documentation

Signed-off-by: Alexis <alexis.challande@trailofbits.com>
sigstore · Dec 13, 2024 · 26d4658 · 26d4658
1 parent 3d60747
commit 26d4658
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 24 deletions.
diff --git a/Makefile b/Makefile
@@ -4,7 +4,7 @@ PY_MODULE := sigstore
 
 ALL_PY_SRCS := $(shell find $(PY_MODULE) -name '*.py') \
 	$(shell find test -name '*.py') \
-	$(shell find scripts -name '*.py') \
+	$(shell find docs/scripts -name '*.py') \
 
 # Optionally overriden by the user, if they're using a virtual environment manager.
 VENV ?= env
@@ -68,7 +68,8 @@ lint: $(VENV)/pyvenv.cfg
 		ruff check $(ALL_PY_SRCS) && \
 		mypy $(PY_MODULE) && \
 		bandit -c pyproject.toml -r $(PY_MODULE) && \
-		interrogate --fail-under 100 -c pyproject.toml $(PY_MODULE)
+		interrogate --fail-under 100 -c pyproject.toml $(PY_MODULE) && \
+		python docs/scripts/gen_ref_pages.py --check
 
 .PHONY: reformat
 reformat: $(VENV)/pyvenv.cfg
@@ -98,7 +99,8 @@ gen-x509-testcases: $(VENV)/pyvenv.cfg
 .PHONY: doc
 doc: $(VENV)/pyvenv.cfg
 	. $(VENV_BIN)/activate && \
-		mkdocs --site-dir html
+		python docs/scripts/gen_ref_pages.py --overwrite && \
+		mkdocs build --strict --site-dir html
 
 .PHONY: package
 package: $(VENV)/pyvenv.cfg

diff --git a/docs/index.md b/docs/index.md
@@ -11,7 +11,7 @@ else!
 * Support for keyless signature generation and verification with [Sigstore](https://www.sigstore.dev/)
 * Support for signing with ["ambient" OpenID Connect identities](./signing.md#signing-with-ambient-credentials)
 * A comprehensive [CLI](#using-sigstore) and corresponding
-  [importable Python API](./API/index.md)
+  [importable Python API](./api/index.md)
 
 ## Installing `sigstore`
 

diff --git a/scripts/gen_ref_pages.py → docs/scripts/gen_ref_pages.py b/scripts/gen_ref_pages.py → docs/scripts/gen_ref_pages.py
@@ -16,13 +16,13 @@
 import sys
 from pathlib import Path
 
-root = Path(__file__).parent.parent
+root = Path(__file__).parent.parent.parent
 src = root / "sigstore"
-api_root = root / "docs" / "API"
+api_root = root / "docs" / "api"
 
 
 def main(args: argparse.Namespace) -> None:
-    """Main script"""
+    """Main script."""
     if args.overwrite:
         shutil.rmtree(api_root, ignore_errors=True)
     elif not args.check and api_root.exists():
@@ -32,11 +32,10 @@ def main(args: argparse.Namespace) -> None:
     seen = set()
     for path in src.rglob("*.py"):
         module_path = path.relative_to(src).with_suffix("")
-        doc_path = path.relative_to(src).with_suffix(".md")
-        full_doc_path = api_root / doc_path.with_suffix(".md")
+        full_doc_path = api_root / path.relative_to(src).with_suffix(".md")
 
-        parts = tuple(module_path.parts)
-        if any(part.startswith("_") for part in parts):
+        # Exclude private entries
+        if any(part.startswith("_") for part in module_path.parts):
             continue
 
         if args.check:
@@ -65,7 +64,7 @@ def main(args: argparse.Namespace) -> None:
             print(f"Found leftover documentation file: {diff}", file=sys.stderr)
             sys.exit(1)
     else:
-        print("API doc generated - don't forget to update the nav section.")
+        print("API doc generated.")
 
 
 if __name__ == "__main__":

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -3,6 +3,7 @@
 site_name: sigstore-python
 site_url: https://sigstore.github.io/sigstore-python
 repo_url: https://github.com/sigstore/sigstore-python
+site_description: sigstore-python, a Sigstore client written in Python
 repo_name: sigstore-python
 edit_uri: edit/main/docs/
 theme:
@@ -12,10 +13,13 @@ theme:
   logo: assets/images/logo.png
   features:
     - content.action.edit
+    - content.code.copy
     - header.autohide
     - navigation.instant
     - navigation.instant.progress
     - navigation.footer
+    - search.highlight
+    - search.suggest
   palette:
     primary: custom
   font:
@@ -33,15 +37,15 @@ nav:
       - Offline Verification: advanced/offline.md
   # begin-api-section
   - API:
-      - API/index.md
-      - Models: API/models.md
-      - Errors: API/errors.md
-      - Hashes: API/hashes.md
-      - OIDC: API/oidc.md
-      - Sign: API/sign.md
+      - api/index.md
+      - Models: api/models.md
+      - Errors: api/errors.md
+      - Hashes: api/hashes.md
+      - OIDC: api/oidc.md
+      - Sign: api/sign.md
       - Verify:
-          - Policy: API/verify/policy.md
-          - Verifier: API/verify/verifier.md
+          - Policy: api/verify/policy.md
+          - Verifier: api/verify/verifier.md
   # end-api-section
 markdown_extensions:
   - admonition
@@ -54,11 +58,21 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
-          import:
-            - url: https://docs.python-requests.org/en/master/objects.inv
-              domains: [std, py]
           options:
-            show_bases: true
+            members_order: source
+            unwrap_annotated: true
+            modernize_annotations: true
+            merge_init_into_class: true
+            docstring_section_style: spacy
+            signature_crossrefs: true
+            show_symbol_type_toc: true
+            filters:
+              - '!^_'
+validation:
+  omitted_files: warn
+  unrecognized_links: warn
+  anchors: warn
+  not_found: warn
 
 extra:
   generator: false