Update documentation

Signed-off-by: Alexis <alexis.challande@trailofbits.com>

.github/workflows/docs.yml

@@ -15,9 +15,7 @@ jobs:
 
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
         with:
-          # NOTE: We use 3.10+ typing syntax via future, which pdoc only
-          # understands if it's actually run with Python 3.10 or newer.
-          python-version: ">= 3.10"
+          python-version: "3.x"
           cache: "pip"
           cache-dependency-path: pyproject.toml
 

Makefile

@@ -3,7 +3,8 @@ SHELL := /bin/bash
 PY_MODULE := sigstore
 
 ALL_PY_SRCS := $(shell find $(PY_MODULE) -name '*.py') \
-	$(shell find test -name '*.py')
+	$(shell find test -name '*.py') \
+	$(shell find scripts -name '*.py') \
 
 # Optionally overriden by the user, if they're using a virtual environment manager.
 VENV ?= env
@@ -97,7 +98,7 @@ gen-x509-testcases: $(VENV)/pyvenv.cfg
 .PHONY: doc
 doc: $(VENV)/pyvenv.cfg
 	. $(VENV_BIN)/activate && \
-		pdoc --output-directory html $(PY_MODULE)
+		mkdocs --site-dir html
 
 .PHONY: package
 package: $(VENV)/pyvenv.cfg

docs/API/index.md

@@ -0,0 +1,6 @@
+!!! note
+
+    The API reference is automatically generated from the docstrings
+
+:::sigstore
+        

docs/index.md

@@ -9,9 +9,9 @@ else!
 ## Features
 
 * Support for keyless signature generation and verification with [Sigstore](https://www.sigstore.dev/)
-* Support for signing with ["ambient" OpenID Connect identities](https://github.com/sigstore/sigstore-python#signing-with-ambient-credentials)
-* A comprehensive [CLI](https://github.com/sigstore/sigstore-python#usage) and corresponding
-  [importable Python API](https://sigstore.github.io/sigstore-python)
+* 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)
 
 ## Installing `sigstore`
 

docs/stylesheets/custom.css

@@ -0,0 +1,5 @@
+/* From https://github.com/sigstore/community/blob/main/artwork/Sigstore_BrandGuide_March2023.pdf */
+:root {
+  --md-primary-fg-color:        #2e2f71;
+  --md-primary-bg-color:         #f9f7ef;
+}

docs/verify.md

@@ -20,7 +20,7 @@ $ sigstore --staging verify identity --cert-identity "a@tny.town" --cert-oidc-is
 
 ## Verifying from GitHub Actions
 
-If your signatures are coming from GitHub Actions (e.g., a workflow that uses its [ambient credentials](#signing-with-ambient-credentials)),
+If your signatures are coming from GitHub Actions (e.g., a workflow that uses its [ambient credentials](./signing.md#signing-with-ambient-credentials)),
 then you can use the `sigstore verify github` subcommand to verify
 claims more precisely than `sigstore verify identity` allows.
 

mkdocs.yml

@@ -9,13 +9,40 @@ theme:
   name: material
   icon:
     repo: fontawesome/brands/github
+  logo: assets/images/logo.png
   features:
     - content.action.edit
     - header.autohide
     - navigation.instant
     - navigation.instant.progress
     - navigation.footer
-
+  palette:
+    primary: custom
+  font:
+    text: Inter
+extra_css:
+  - stylesheets/custom.css
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Signing: signing.md
+  - Verifying: verify.md
+  - Policy: policy.md
+  - Advanced:
+      - Custom Root of Trust: advanced/custom_trust.md
+      - 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
+      - Verify:
+          - Policy: API/verify/policy.md
+          - Verifier: API/verify/verifier.md
+  # end-api-section
 markdown_extensions:
   - admonition
   - pymdownx.details
@@ -37,4 +64,6 @@ extra:
   generator: false
   social:
     - icon: fontawesome/brands/slack
-      link: https://sigstore.slack.com
+      link: https://sigstore.slack.com
+    - icon: fontawesome/brands/x-twitter
+      link: https://twitter.com/projectsigstore

scripts/gen_ref_pages.py

@@ -11,25 +11,73 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+import argparse
+import shutil
+import sys
 from pathlib import Path
 
 root = Path(__file__).parent.parent
 src = root / "sigstore"
+api_root = root / "docs" / "API"
+
 
-def main():
+def main(args: argparse.Namespace) -> None:
+    """Main script"""
+    if args.overwrite:
+        shutil.rmtree(api_root, ignore_errors=True)
+    elif not args.check and api_root.exists():
+        print(f"API root {api_root} already exists, skipping.")
+        sys.exit(0)
+
+    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 = root / "docs" / "API" / doc_path.with_suffix(".md")
+        full_doc_path = api_root / doc_path.with_suffix(".md")
 
         parts = tuple(module_path.parts)
         if any(part.startswith("_") for part in parts):
             continue
 
+        if args.check:
+            if not full_doc_path.is_file():
+                sys.exit(1)
+
         full_doc_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(full_doc_path, "w") as f:
+        with full_doc_path.open("w") as f:
             f.write(f":::sigstore.{str(module_path).replace('/', '.')}\n ")
 
+        seen.add(full_doc_path)
+
+    # Add the root
+    with (api_root / "index.md").open("w") as f:
+        f.write("""!!! note
+
+    The API reference is automatically generated from the docstrings
+
+:::sigstore
+        """)
+
+    seen.add(api_root / "index.md")
+
+    if args.check:
+        if diff := set(api_root.rglob("*.md")).symmetric_difference(seen):
+            print(f"Found leftover documentation file: {diff}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print(f"API doc generated - don't forget to update the nav section."    )
+
 if __name__ == "__main__":
-    main()
+    parser = argparse.ArgumentParser(
+        description="Generate the structure for the API documentation."
+    )
+    parser.add_argument("--overwrite", action="store_true", default=False)
+    parser.add_argument("--check", action="store_true", default=False)
+
+    arguments = parser.parse_args()
+
+    if arguments.check and arguments.overwrite:
+        print("You can't specify both --check and --overwrite.", file=sys.stderr)
+        sys.exit(1)
+
+    main(arguments)