Restructure documentation into User, Administrator, and Developer guides#283
Merged
Conversation
The flat 16-page docs are reorganized into three audience-focused sections with a nested mkdocs nav: - User Guide (docs/user/): install, getting started, a new consolidated Loading Configurations page (all from_* constructors including JSON/XML), remediation workflows (now covering plugins, transform callbacks, and NETCONF rendering), tags, future-config (updated for the #269 negation semantics and prune_empty_branches), unified diff (previously missing from the nav), reporting (trimmed ~40%), config views (updated for the v4 mixin model), and set-style platforms (generalized from the JunOS-only page). - Administrator Guide (docs/admin/): the per-platform reference, customizing driver rules (including a new post-load-callback override recipe), custom drivers and the registry, and loading rules from YAML - carved out of the 1049-line drivers.md. - Developer Guide (docs/dev/): refreshed architecture, the driver rule model reference, creating a platform driver, a new contributing page, and an API reference extended to the full v4 public surface. index.md is rewritten as a landing page with a runnable quick example (output verified against the library) and audience-based entry points. README/CONTRIBUTING links updated; mkdocs build --strict passes with zero warnings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
The docs were 3,750 lines across 16 flat pages —
unified-diff.mdwasn't even in the nav, anddrivers.md(1,049 lines) mixed user, admin, and developer content. This restructures everything into three audience-focused guides with a nested nav:User Guide (
docs/user/) — install → getting started → Loading Configurations (new page consolidating all seven constructors, includingfrom_json/from_xml) → remediation workflows (now coveringIncompatibleDriverErrorvalidation, transform callbacks, plugins, andremediation_netconf_xml) → tags → future-config (updated with the #269 negation-resolution semantics andprune_empty_branches) → unified diff → reporting (trimmed ~40% of redundancy) → config views (rewritten for the v4 capability-mixin model) → set-style platforms (generalized from JunOS-only to JunOS/VyOS/Nokia SRL).Administrator Guide (
docs/admin/) — supported-platform reference, customizing driver rules (including a new recipe for overriding post-load callbacks, e.g. keeping IOS ACL remarks — the #271 resolution), custom drivers + the registry, and loading rules from YAML.Developer Guide (
docs/dev/) — refreshed architecture (tree_algorithms, registry, formats, plugins modules), the driver rule-model reference (unifiedNegationRule), creating a platform driver end-to-end, a new Contributing page, and an API reference extended to the full v4 public surface.index.mdis rewritten as a landing page: what/why, a runnable quick example (output verified by actually running it), and "where to go next" entry points per audience. Every code example was verified against the v4 source rather than carried over from the old docs. README and CONTRIBUTING links updated to the new paths.Test plan
poetry run mkdocs build --strict— zero warnings (all nav entries, internal links, and mkdocstrings targets resolve).poetry run ./scripts/build.py lint-and-test— "No issues found".drivers.mdis accounted for in the disposition (nothing dropped).🤖 Generated with Claude Code