docs: restructure navigation into Configuration/Deployment/API/Operations/Background - #4472
Draft
reinkrul wants to merge 5 commits into
Draft
docs: restructure navigation into Configuration/Deployment/API/Operations/Background#4472reinkrul wants to merge 5 commits into
reinkrul wants to merge 5 commits into
Conversation
…ions/Background Reorganizes the Sphinx docs from Integrating/Deployment & Configuration/ Technology into five top-level sections matching how operators actually need to find things: Configuration (server options, per-use-case config, legacy did:nuts config), Deployment, API, Operations (migration, key rotation, certificate maintenance, base-URL changes, CLI reference), and Background (conceptual reference material, to be relocated later). Along the way: split certificates.rst and version-incompatibilities.rst across their new homes, merged audit-logging.rst into logging.rst, moved contributor/release docs out of the Sphinx tree into root-level Markdown (DEVELOPMENT.md, RELEASING.md, CONTRIBUTING.md) following the existing COLLABORATORS.md/SECURITY.md convention, and dropped the now-redundant contact.rst. Updated docs/generate_docs.go's hardcoded output paths and regenerated the options/CLI reference tables, expanded the `url` flag's help text with the domain-selection guidance previously only in prose, and fixed two stale doc links (README_template.rst's development include, a dead readthedocs link in didman/v1.yaml) uncovered while moving files. Assisted by AI Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
Contributor
|
Coverage Impact This PR will not change total coverage. Modified Files with Diff Coverage (2)
🤖 Increase coverage with AI coding...🚦 See full report on Qlty Cloud » 🛟 Help
|
…t sentence
The "regenerate this table via make docs" note is a maintainer instruction,
not something a node operator needs to see, and referenced a Makefile
target that no longer exists (it's cli-docs). Dropped it from the two
operator-facing options pages and folded the instruction into
DEVELOPMENT.md's existing regeneration section instead.
Also fixed a sentence in the legacy did:nuts client-authentication section
that only made sense next to the did:x509 section it used to sit beside
in certificates.rst before this PR split them into separate pages ("Nuts-
node versions before v6 only use..." read as an orphaned historical claim
once the did:x509 contrast it was set up against moved elsewhere).
Assisted by AI
Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
It was three sentences that only pointed to Discovery, Access policies, and Certificate revocation handling without adding anything of its own. Folded its one real piece of content (trust is configured via Discovery + Policy definition files) into background/did.rst's existing did:x509 section, which already explains why did:x509 uses certificates as its root of trust. Assisted by AI Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
Key rotation: the page claimed the rotation procedure was "two fold... performed independently" but only ever documented one step (adding a key) — removal was cut when it was found unsupported, but the "two fold" framing and the orphaned "1." numbering were never cleaned up. Reframed the page around what's actually supported: adding a new key. Removal still isn't supported, so this isn't full rotation yet, but it's real, useful, working operator guidance and worth keeping. Release notes: the Unreleased section used Markdown-style "## New features" / "## Security" headers, which don't render as headings in RST (Sphinx renders them as literal text) and don't match every other section in the file, which uses proper underlined RST headers. Assisted by AI Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
The node's URL section covers a decision independent of the rest of the server options table (it doesn't change, unlike most options, and has its own operational procedure for changing it), so it gets its own Configuration page instead of being a subsection of Options. Also dropped "Choosing" from the title. Dropped `nuts crypto fs2vault` from the generated CLI reference and the Vault migration guidance in storage.rst — it's not something we want operators reaching for right now. The command itself is untouched; this only stops recommending it in docs. Assisted by AI Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the Sphinx docs nav from Integrating / Deployment & Configuration / Technology / Development / Other into:
Changelog (moves/splits/merges, so this doesn't need line-by-line review)
deployment/configuration.rst→configuration/options.rst; did:nuts/gRPC options table split out toconfiguration/legacy-did-nuts.rst; added a "Choosing the node's URL" section.deployment/policy.rst→configuration/usecase/access-policies.rst,deployment/verifiable-credentials.rst→usecase/verifiable-credentials.rst,deployment/discovery.rst→usecase/discovery.rst.deployment/certificates.rstsplit 4 ways: gRPC client-auth mechanics →configuration/legacy-did-nuts.rst; did:x509 trust config + background →background/did.rst's existing did:x509 section (a standalone "Certificates (did:x509)" use-case page was cut after review — it only pointed at three other pages without adding anything of its own); CRL/soft-fail behavior → newoperations/certificate-revocation.rst.deployment/domain.rstsplit: "choosing" guidance →configuration/options.rst(and into theurlflag's help text incore/server_config.go, since that's the source of truth for the generated options table); "changing" procedure → newoperations/base-url-change.rst.integrating/version-incompatibilities.rstsplit: DID-methods/API-version guidance merged intooperations/migration.rst; "Publishing services" section merged intoconfiguration/legacy-did-nuts.rst. Added a matching deprecation note to the VDR v1 OpenAPI spec.deployment/audit-logging.rstmerged intodeployment/logging.rst.integrating/{api,api-authentication,vc}.rst→api/{reference,authentication,verifiable-credentials}.rst.deployment/{migration,key-rotation,cli-reference}.rst→operations/.deployment/oauth.rst,technology/{did,jsonld,security_model}.rst,integrating/supported-protocols-formats.rst→background/.technology/saas.rst→deployment/saas.rst.docs/pages/development/*.rstandcontribute.rst→ rootDEVELOPMENT.md,RELEASING.md,CONTRIBUTING.md(matching the existingCOLLABORATORS.md/SECURITY.mdconvention), plus an API-guidelines section appended todocs/README.md. Verified against current Makefile targets, build tags, and CI workflow filenames — fixed one stale filename along the way.contact.rstdropped.docs/generate_docs.gooutput paths updated for the moved generated tables (server_options*.rst,cli-reference.rst); tables regenerated.make docs" note from the two operator-facing options pages (wrong Makefile target too — it'scli-docs); folded proper guidance intoDEVELOPMENT.md.README_template.rst's deaddocs/pages/development/1-development.rstinclude, and a dead readthedocs link indocs/_static/didman/v1.yaml.Test plan
go build ./...passesgo test ./docs/... ./core/...passesopenid4vciref and two release-notes formatting nits predate this change and are out of scope) — confirmed matching on the actual Read the Docs build for this branchREADME.rstregenerated fromREADME_template.rstviarst_includeand diff reviewed🤖 Generated with Claude Code
https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG