Split troubleshooting, add contributing index, clean VPN structure (#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 dad139434e34d3bbf24fd46c8fa8ea7a54177d0a)

Co-authored-by: Yuriy Andamasov <yuriy@vyos.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

0 files changed, 0 insertions, 0 deletions