Restructure documentation (#1255)

* Draft a POLICY

Signed-off-by: Alexis <[email protected]>

* Update documentation

Signed-off-by: Alexis <[email protected]>

* Add missing license

Signed-off-by: Alexis <[email protected]>

* Remove pdoc dependency

Signed-off-by: Alexis <[email protected]>

* Update documentation

Signed-off-by: Alexis <[email protected]>

* Improve documentation

Signed-off-by: Alexis <[email protected]>

* Explicit failure reasons

Signed-off-by: Alexis <[email protected]>

* Remove API folder

* Add api folder

* Update policy.md

Signed-off-by: Alexis <[email protected]>

* Remove API folder

Signed-off-by: Alexis <[email protected]>

* Add api folder

Signed-off-by: Alexis <[email protected]>

* Update policy.md

Signed-off-by: Alexis <[email protected]>

---------

Signed-off-by: Alexis <[email protected]>

Author: DarkaMaul

.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
 

.gitignore

@@ -1,3 +1,4 @@
+.cache/
 env/
 pip-wheel-metadata/
 *.egg-info/

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 docs/scripts -name '*.py') \
 
 # Optionally overriden by the user, if they're using a virtual environment manager.
 VENV ?= env
@@ -67,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
@@ -97,7 +99,8 @@ gen-x509-testcases: $(VENV)/pyvenv.cfg
 .PHONY: doc
 doc: $(VENV)/pyvenv.cfg
 	. $(VENV_BIN)/activate && \
-		pdoc --output-directory html $(PY_MODULE)
+		python docs/scripts/gen_ref_pages.py --overwrite && \
+		mkdocs build --strict --site-dir html
 
 .PHONY: package
 package: $(VENV)/pyvenv.cfg

README.md

@@ -18,21 +18,13 @@ else!
 
 * [Features](#features)
 * [Installation](#installation)
-  * [GitHub Actions](#github-actions)
 * [Usage](#usage)
   * [Signing](#signing)
   * [Verifying](#verifying)
     * [Generic identities](#generic-identities)
     * [Signatures from GitHub Actions](#signatures-from-github-actions)
   * [Advanced usage](#advanced-usage)
-* [Example uses](#example-uses)
-  * [Signing with ambient credentials](#signing-with-ambient-credentials)
-  * [Signing with an email identity](#signing-with-an-email-identity)
-  * [Signing with an explicit identity token](#signing-with-an-explicit-identity-token)
-  * [Verifying against a bundle](#verifying-against-a-bundle)
-  * [Offline verification](#offline-verification)
-  * [Verifying a digest instead of a file](#verifying-a-digest-instead-of-a-file)
-  * [Verifying signatures from GitHub Actions](#verifying-signatures-from-github-actions)
+* [Documentation](#documentation)
 * [Licensing](#licensing)
 * [Community](#community)
 * [Contributing](#contributing)
@@ -55,44 +47,17 @@ else!
 python -m pip install sigstore
 ```
 
-Optionally, to install `sigstore` and all its dependencies with [hash-checking mode](https://pip.pypa.io/en/stable/topics/secure-installs/#hash-checking-mode) enabled, run the following:
-
-```console
-python -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txt
-```
-
-This installs the requirements file located [here](https://github.com/sigstore/sigstore-python/blob/main/install/requirements.txt), which is kept up-to-date.
-
-### GitHub Actions
-
-`sigstore-python` has [an official GitHub Action](https://github.com/sigstore/gh-action-sigstore-python)!
-
-You can install it from the
-[GitHub Marketplace](https://github.com/marketplace/actions/gh-action-sigstore-python), or
-add it to your CI manually:
-
-```yaml
-jobs:
-  sigstore-python:
-    steps:
-      - uses: sigstore/[email protected]
-        with:
-          inputs: foo.txt
-```
-
-See the
-[action documentation](https://github.com/sigstore/gh-action-sigstore-python/blob/main/README.md)
-for more details and usage examples.
+See the [installation](https://sigstore.github.io/sigstore-python/installation) page in the documentation for more
+installation options.
 
 ## Usage
 
-For Python API usage, see our [documentation](https://sigstore.github.io/sigstore-python/).
+For Python API usage, see our [API](https://sigstore.github.io/sigstore-python/api/).
 
-You can run `sigstore` as a standalone program, or via `python -m`:
+You can run `sigstore` as a standalone program:
 
 ```console
 sigstore --help
-python -m sigstore --help
 ```
 
 Top-level:
@@ -236,12 +201,7 @@ Output options:
 
 ### Verifying
 
-#### Generic identities
-
-This is the most common verification done with `sigstore`, and therefore
-the one you probably want: you can use it to verify that a signature was
-produced by a particular identity (like `[email protected]`), as attested
-to by a particular OIDC provider (like `https://github.com/login/oauth`).
+#### Identities
 
 <!-- @begin-sigstore-verify-identity-help@ -->
 ```
@@ -281,11 +241,6 @@ Verification options:
 
 #### Signatures from GitHub Actions
 
-If your signatures are coming from GitHub Actions (e.g., a workflow
-that uses its [ambient credentials](#signing-with-ambient-credentials)),
-then you can use the `sigstore verify github` subcommand to verify
-claims more precisely than `sigstore verify identity` allows:
-
 <!-- @begin-sigstore-verify-github-help@ -->
 ```
 usage: sigstore verify github [-h] [-v] [--certificate FILE]
@@ -330,195 +285,9 @@ Verification options:
 ```
 <!-- @end-sigstore-verify-github-help@ -->
 
-## Advanced usage
-
-### Configuring a custom root of trust ("BYO PKI")
-
-Apart from the default and "staging" Sigstore instances, `sigstore` also
-supports "BYO PKI" setups, where a user maintains their own Sigstore
-instance services.
-
-These are supported via the `--trust-config` flag, which accepts a
-JSON-formatted file conforming to the `ClientTrustConfig` message
-in the [Sigstore protobuf specs](https://github.com/sigstore/protobuf-specs).
-This file configures the entire Sigstore instance state, *including* the URIs
-used to access the CA and artifact transparency services as well as the
-cryptographic root of trust itself.
-
-To use a custom client config, prepend `--trust-config` to any `sigstore`
-command:
-
-```console
-$ sigstore --trust-config custom.trustconfig.json sign foo.txt
-$ sigstore --trust-config custom.trustconfig.json verify identity foo.txt ...
-```
-
-## Example uses
+## Documentation
 
-`sigstore` supports a wide variety of workflows and usages. Some common ones are
-provided below.
-
-### Signing with ambient credentials
-
-For environments that support OpenID Connect, `sigstore` supports ambient credential
-detection. This includes many popular CI platforms and cloud providers. See the full list of
-supported environments [here](https://github.com/di/id#supported-environments).
-
-Sign a single file (`foo.txt`) using an ambient OpenID Connect credential,
-saving the bundle to `foo.txt.sigstore.json`:
-
-```console
-$ python -m sigstore sign foo.txt
-```
-
-### Signing with an email identity
-
-`sigstore` can use an OAuth2 + OpenID flow to establish an email identity,
-allowing you to request signing certificates that attest to control over
-that email.
-
-Sign a single file (`foo.txt`) using the OAuth2 flow, saving the
-bundle to `foo.txt.sigstore.json`:
-
-```console
-$ python -m sigstore sign foo.txt
-```
-
-By default, `sigstore` attempts to do
-[ambient credential detection](#signing-with-ambient-credentials), which may preempt
-the OAuth2 flow. To force the OAuth2 flow, you can explicitly disable ambient detection:
-
-```console
-$ python -m sigstore sign --oidc-disable-ambient-providers foo.txt
-```
-
-### Signing with an explicit identity token
-
-If you can't use an ambient credential or the OAuth2 flow, you can pass a pre-created
-identity token directly into `sigstore sign`:
-
-```console
-$ python -m sigstore sign --identity-token YOUR-LONG-JWT-HERE foo.txt
-```
-
-Note that passing a custom identity token does not circumvent Fulcio's requirements,
-namely the Fulcio's supported identity providers and the claims expected within the token.
-
-### Verifying against a bundle
-
-By default, `sigstore verify identity` will attempt to find a `<filename>.sigstore.json`
-or `<filename>.sigstore` in the same directory as the file being verified:
-
-```console
-# looks for foo.txt.sigstore.json
-$ python -m sigstore verify identity foo.txt \
-    --cert-identity '[email protected]' \
-    --cert-oidc-issuer 'https://github.com/login/oauth'
-```
-
-Multiple files can be verified at once:
-
-```console
-# looks for {foo,bar}.txt.sigstore.json
-$ python -m sigstore verify identity foo.txt bar.txt \
-    --cert-identity '[email protected]' \
-    --cert-oidc-issuer 'https://github.com/login/oauth'
-```
-
-### Offline verification
-
-> [!IMPORTANT]
-> Because `--offline` disables trust root updates, `sigstore-python` falls back
-> to the latest cached trust root or, if none exists, the trust root baked
-> into `sigstore-python` itself. Like with any other offline verification,
-> this means that users may miss trust root changes (such as new root keys,
-> or revocations) unless they separately keep the trust root up-to-date.
->
-> Users who need to operationalize offline verification may wish to do this
-> by distributing their own trust configuration; see
-> [Configuring a custom root of trust](#configuring-a-custom-root-of-trust-byo-pki).
-
-During verification, there are two kinds of network access that `sigstore-python`
-*can* perform:
-
-1. When verifying against "detached" materials (e.g. separate `.crt` and `.sig`
-   files), `sigstore-python` can perform an online transparency log lookup.
-2. By default, during all verifications, `sigstore-python` will attempt to
-   refresh the locally cached root of trust via a TUF update.
-
-When performing bundle verification (i.e. `.sigstore` or `.sigstore.json`),
-(1) does not apply. However, (2) can still result in online accesses.
-
-To perform **fully** offline verification, pass `--offline` to your
-`sigstore verify` subcommand:
-
-```bash
-$ python -m sigstore verify identity foo.txt \
-    --offline \
-    --cert-identity '[email protected]' \
-    --cert-oidc-issuer 'https://github.com/login/oauth'
-```
-
-Alternatively, users may choose to bypass TUF entirely by passing
-an entire trust configuration to `sigstore-python` via `--trust-config`:
-
-```bash
-$ python -m sigstore --trust-config public.trustconfig.json verify identity ...
-```
-
-This will similarly result in fully offline operation, as the trust
-configuration contains a full trust root.
-
-### Verifying a digest instead of a file
-
-`sigstore-python` supports verifying digests directly, without requiring the artifact to be
-present. The digest should be prefixed with the `sha256:` string:
-
-```console
-$ python -m sigstore verify identity sha256:ce8ab2822671752e201ea1e19e8c85e73d497e1c315bfd9c25f380b7625d1691 \
-    --cert-identity '[email protected]' \
-    --cert-oidc-issuer 'https://github.com/login/oauth'
-    --bundle 'foo.txt.sigstore.json'
-```
-
-### Verifying signatures from GitHub Actions
-
-`sigstore verify github` can be used to verify claims specific to signatures coming from GitHub
-Actions. `sigstore-python` signs releases via GitHub Actions, so the examples below are working
-examples of how you can verify a given `sigstore-python` release.
-
-When using `sigstore verify github`, you must pass `--cert-identity` or `--repository`, or both.
-Unlike `sigstore verify identity`, `--cert-oidc-issuer` is **not** required (since it's
-inferred to be GitHub Actions).
-
-Verifying with `--cert-identity`:
-
-```console
-$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
-    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
-    --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0
-```
-
-Verifying with `--repository`:
-
-```console
-$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
-    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
-    --repository sigstore/sigstore-python
-```
-
-Additional GitHub Actions specific claims can be verified like so:
-
-```console
-$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
-    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
-    --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0 \
-    --trigger release \
-    --sha 66581529803929c3ccc45334632ccd90f06e0de4 \
-    --name Release \
-    --repository sigstore/sigstore-python \
-    --ref refs/tags/v0.10.0
-```
+`sigstore` documentation is available on [https://sigstore.github.io/sigstore-python](https://sigstore.github.io/sigstore-python)
 
 ## Licensing
 
@@ -544,9 +313,3 @@ Everyone interacting with this project is expected to follow the
 
 Should you discover any security issues, please refer to sigstore's [security
 process](https://github.com/sigstore/.github/blob/main/SECURITY.md).
-
-### SLSA Provenance
-This project emits a SLSA provenance on its release! This enables you to verify the integrity
-of the downloaded artifacts and ensured that the binary's code really comes from this source code.
-
-To do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance).

docs/advanced/custom_trust.md

@@ -0,0 +1,22 @@
+# Custom Root of Trust
+
+### Configuring a custom root of trust ("BYO PKI")
+
+Apart from the default and "staging" Sigstore instances, `sigstore` also
+supports "BYO PKI" setups, where a user maintains their own Sigstore
+instance services.
+
+These are supported via the `--trust-config` flag, which accepts a
+JSON-formatted file conforming to the `ClientTrustConfig` message
+in the [Sigstore protobuf specs](https://github.com/sigstore/protobuf-specs).
+This file configures the entire Sigstore instance state, *including* the URIs
+used to access the CA and artifact transparency services as well as the
+cryptographic root of trust itself.
+
+To use a custom client config, prepend `--trust-config` to any `sigstore`
+command:
+
+```console
+$ sigstore --trust-config custom.trustconfig.json sign foo.txt
+$ sigstore --trust-config custom.trustconfig.json verify identity foo.txt ...
+```