Skip to content

split README into topic-based guides - #16

Merged
Luca (lukka) merged 3 commits into
mainfrom
lukka/docs-reorg
Sep 17, 2026
Merged

Luca (lukka) merged 3 commits into
mainfrom
lukka/docs-reorg

Conversation

@lukka

@lukka Luca (lukka) commented Sep 15, 2026

Copy link
Copy Markdown
Member

This pull request reorganizes the Microsoft C++ Language Server documentation into topic-based guides and reference pages under docs/. The root README stays focused on the project overview, full inline quick start, essential links, and legal notices.

Documentation changes

  • Moves detailed installation, authentication, compilation-database, configuration, indexing, troubleshooting, command-line, and LSP-feature documentation into dedicated pages.
  • Adds docs/index.md as the documentation index, organized into Guides and Reference. The root README remains the only file named README in the repository.
  • Preserves existing README section links through compatibility anchors beside the relevant replacement topic links, and updates cross-links throughout the documentation.
  • Adds guidance for disabling and re-enabling WCI through the per-user state file, including its scope, restart requirements, trade-offs, and precautions for preserving existing settings and authentication data.
  • Documents --check=<file> and --check-compile-commands=<path>, including standalone usage, prerequisites, compilation-database discovery, and check-mode exit codes.
  • Keeps extractor-authoring guidance linked from the compilation-database guide, removes unrelated resource links and maintenance instructions from the index, and retains feedback and data-collection guidance.

Manual validation

  • All 16 repository Markdown files render, and all 62 local links resolve.
  • All three JSON examples parse; legacy README anchors and the quick-start/WCI ordered-list structure are preserved.
  • Documentation whitespace checks pass.

This PR changes documentation only; it does not change language-server or plugin runtime behavior.

Comment thread docs/command-line-options.md
@lukka
Luca (lukka) marked this pull request as ready for review September 16, 2026 00:32
@lukka

Copy link
Copy Markdown
Member Author

Looks like we need to add --check= and --check-compile-commands=

Glen Chung (@kuchungmsft) thanks, fixed in 53c1088

Comment thread docs/README.md Outdated
Comment thread docs/README.md Outdated
Comment thread docs/README.md Outdated
Comment thread docs/README.md Outdated
Comment thread docs/README.md Outdated
Comment thread README.md

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The documentation-only reorganization is coherent, preserves compatibility anchors, and has valid local links.

Review effort: Balanced
Findings: None

What changed in this PR

Reorganizes detailed documentation into focused guides while keeping the README concise and preserving legacy anchors.

Changes:

  • Adds a documentation index with topic-based guides and references.
  • Documents WCI controls and standalone source checking.
  • Retains quick-start, feedback, and legal information in the README.
File Description
README.md Streamlines overview and links to detailed guides.
docs/​index.md Adds the central documentation index.
docs/​installation.md Covers installation and platform requirements.
docs/​authentication.md Covers authentication and enterprise login.
docs/​compile-commands.md Documents compilation database generation.
docs/​configuration.md Documents server configuration and discovery.
docs/​indexing.md Covers indexing controls and WCI.
docs/​troubleshooting.md Consolidates diagnostics and feedback guidance.
docs/​command-line-options.md Documents CLI options and check mode.
docs/​lsp-features.md Lists supported LSP capabilities.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@lukka
Luca (lukka) merged commit 395d87d into main Sep 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants