Split troubleshooting, add contributing index, clean VPN structure#1804
Merged
Split troubleshooting, add contributing index, clean VPN structure#1804
Conversation
Covers 4 work streams: mechanical fixes (headings, indentation, typos), content quality (TODO flags, TBD fills, stub markers), structural reorganization (troubleshooting split, contributing index, VPN cleanup), and RTD platform cleanup (hide versions, delete stale redirects). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…numbers Addresses 10 reviewer findings: corrected heading character types (^ was actually -), removed ip.rst (already correct), updated file count from 37 to 35, listed all 13 tab-containing files, fixed troubleshooting line count to 460, added heading level guidance for split pages, clarified contributing/documentation.rst scope, removed current from hide list, added rollback verification step, updated success criteria. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
16 tasks across 4 work streams: mechanical fixes (PR 1, tasks 1-6), content quality (PR 2, tasks 7-10), structural reorg (PR 3, tasks 11-14), and RTD platform cleanup (tasks 15-16). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Replace hardcoded RTD token with $RTD_TOKEN variable - Fix Task 7 heading reference to be format-agnostic - Correct RTD PATCH expected response (200, not 204) - Fix version verification to check hidden field, not active - Account for blank lines 402-403 in troubleshooting split - Clarify start/stop_vyoslinter handling in system.rst Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split monolithic 460-line troubleshooting/index.rst into: - connectivity.rst (ping, traceroute, mtr, IPv6 discovery) - interfaces.rst (interface naming, MAC addresses) - monitoring.rst (traffic dumps, bandwidth, iperf) - terminal.rst (console clearing, counter resets) - system.rst (boot steps, system information) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the documentation to improve navigation and maintainability by splitting a large troubleshooting page into focused sub-pages, adding a contributing index, and cleaning up VPN section placeholders.
Changes:
- Split
docs/troubleshooting/index.rstinto a small index page plus five topic pages (connectivity, interfaces, monitoring, terminal, system). - Add
docs/contributing/index.rstand simplify the root “Development” toctree to point to it. - Clean up VPN/IPsec indexes by removing placeholder sections and integrating
dmvpninto the main VPN toctree.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/troubleshooting/index.rst | Replaced long monolithic content with a toctree to sub-pages |
| docs/troubleshooting/connectivity.rst | New connectivity troubleshooting page (ping/traceroute/mtr/IPv6 discovery) |
| docs/troubleshooting/interfaces.rst | New interface renaming/MAC troubleshooting page |
| docs/troubleshooting/monitoring.rst | New monitoring page (traffic dumps, bandwidth, bandwidth-test, monitor command) |
| docs/troubleshooting/terminal.rst | New terminal/console “clear counters” page |
| docs/troubleshooting/system.rst | New system info/boot steps page with reference definitions |
| docs/contributing/index.rst | New contributing landing page with toctree |
| docs/index.rst | Simplified “Development” toctree to point at contributing index; rewrapped front page card text |
| docs/configuration/vpn/index.rst | Integrated dmvpn into main toctree; removed placeholder content |
| docs/configuration/vpn/ipsec/index.rst | Removed “pages to sort” placeholder and empty toctree |
| docs/superpowers/specs/2026-03-21-docs-improvements-design.md | Added design spec describing docs improvements workstreams |
| docs/superpowers/plans/2026-03-21-docs-improvements.md | Added implementation plan detailing step-by-step execution |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…fixes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Shorten :ref: display text on two lines that exceeded the 80-char limit: "Virtual Environment" -> "VM" (line 24, 90 -> 73 chars) and "Configuration Blueprints" -> "Blueprints" (line 51, 85 -> 71 chars). Both targets remain correct; display text is clear in context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Member
Author
Specs moved to personal branch yuriy/docs-modernization-specs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Member
|
@Mergifyio backport circinus |
✅ Backports have been createdDetails
|
mergify bot
pushed a commit
that referenced
this pull request
Apr 2, 2026
…1804) * Add design spec for documentation improvements Covers 4 work streams: mechanical fixes (headings, indentation, typos), content quality (TODO flags, TBD fills, stub markers), structural reorganization (troubleshooting split, contributing index, VPN cleanup), and RTD platform cleanup (hide versions, delete stale redirects). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix spec issues from review: correct heading chars, tab counts, line numbers Addresses 10 reviewer findings: corrected heading character types (^ was actually -), removed ip.rst (already correct), updated file count from 37 to 35, listed all 13 tab-containing files, fixed troubleshooting line count to 460, added heading level guidance for split pages, clarified contributing/documentation.rst scope, removed current from hide list, added rollback verification step, updated success criteria. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add implementation plan for documentation improvements 16 tasks across 4 work streams: mechanical fixes (PR 1, tasks 1-6), content quality (PR 2, tasks 7-10), structural reorg (PR 3, tasks 11-14), and RTD platform cleanup (tasks 15-16). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix 6 issues from plan review - Replace hardcoded RTD token with $RTD_TOKEN variable - Fix Task 7 heading reference to be format-agnostic - Correct RTD PATCH expected response (200, not 204) - Fix version verification to check hidden field, not active - Account for blank lines 402-403 in troubleshooting split - Clarify start/stop_vyoslinter handling in system.rst Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: split troubleshooting into 5 focused sub-pages Split monolithic 460-line troubleshooting/index.rst into: - connectivity.rst (ping, traceroute, mtr, IPv6 discovery) - interfaces.rst (interface naming, MAC addresses) - monitoring.rst (traffic dumps, bandwidth, iperf) - terminal.rst (console clearing, counter resets) - system.rst (boot steps, system information) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor: create contributing/index.rst, simplify root toctree * fix: remove 'pages to sort' placeholders from VPN section * fix: wrap long lines in index.rst for linter compliance * Add design spec for sitemap generation improvement * Fix sitemap spec: remove invalid sitemap_excludes, add version pin * fix: address Copilot review suggestions — grammar, typos, RST markup fixes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: resolve remaining long lines in index.rst Shorten :ref: display text on two lines that exceeded the 80-char limit: "Virtual Environment" -> "VM" (line 24, 90 -> 73 chars) and "Configuration Blueprints" -> "Blueprints" (line 51, 85 -> 71 chars). Both targets remain correct; display text is clear in context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: remove superpowers specs from PR Specs moved to personal branch yuriy/docs-modernization-specs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> (cherry picked from commit dad1394)
5 tasks
dmbaturin
pushed a commit
that referenced
this pull request
Apr 3, 2026
…1804) (#1815) * Add design spec for documentation improvements Covers 4 work streams: mechanical fixes (headings, indentation, typos), content quality (TODO flags, TBD fills, stub markers), structural reorganization (troubleshooting split, contributing index, VPN cleanup), and RTD platform cleanup (hide versions, delete stale redirects). * Fix spec issues from review: correct heading chars, tab counts, line numbers Addresses 10 reviewer findings: corrected heading character types (^ was actually -), removed ip.rst (already correct), updated file count from 37 to 35, listed all 13 tab-containing files, fixed troubleshooting line count to 460, added heading level guidance for split pages, clarified contributing/documentation.rst scope, removed current from hide list, added rollback verification step, updated success criteria. * Add implementation plan for documentation improvements 16 tasks across 4 work streams: mechanical fixes (PR 1, tasks 1-6), content quality (PR 2, tasks 7-10), structural reorg (PR 3, tasks 11-14), and RTD platform cleanup (tasks 15-16). * Fix 6 issues from plan review - Replace hardcoded RTD token with $RTD_TOKEN variable - Fix Task 7 heading reference to be format-agnostic - Correct RTD PATCH expected response (200, not 204) - Fix version verification to check hidden field, not active - Account for blank lines 402-403 in troubleshooting split - Clarify start/stop_vyoslinter handling in system.rst * refactor: split troubleshooting into 5 focused sub-pages Split monolithic 460-line troubleshooting/index.rst into: - connectivity.rst (ping, traceroute, mtr, IPv6 discovery) - interfaces.rst (interface naming, MAC addresses) - monitoring.rst (traffic dumps, bandwidth, iperf) - terminal.rst (console clearing, counter resets) - system.rst (boot steps, system information) * refactor: create contributing/index.rst, simplify root toctree * fix: remove 'pages to sort' placeholders from VPN section * fix: wrap long lines in index.rst for linter compliance * Add design spec for sitemap generation improvement * Fix sitemap spec: remove invalid sitemap_excludes, add version pin * fix: address Copilot review suggestions — grammar, typos, RST markup fixes * fix: resolve remaining long lines in index.rst Shorten :ref: display text on two lines that exceeded the 80-char limit: "Virtual Environment" -> "VM" (line 24, 90 -> 73 chars) and "Configuration Blueprints" -> "Blueprints" (line 51, 85 -> 71 chars). Both targets remain correct; display text is clear in context. * chore: remove superpowers specs from PR Specs moved to personal branch yuriy/docs-modernization-specs. --------- (cherry picked from commit dad1394) Co-authored-by: Yuriy Andamasov <yuriy@vyos.io> Co-authored-by: Claude Opus 4.6 (1M context) <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
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
troubleshooting/index.rst(460 lines) into 5 focused sub-pages: connectivity, interfaces, monitoring, terminal, systemcontributing/index.rstwith toctree, simplify root index.rstTest plan
.. _boot-steps:and.. _troubleshooting:cross-references still workGenerated with Claude Code