Refactor documentation generation framework

[vinniefalco]

Summary by CodeRabbit

• Documentation
  • Restructured tutorials with new beginner-focused sections covering foundational coroutines and I/O concepts
  • Streamlined documentation layout and removed legacy tutorial mappings for improved clarity
  • Simplified example programs section

[coderabbitai]

📝 Walkthrough

Walkthrough

The documentation rebuild file was restructured, shifting from a prescriptive multi-part tutorial and style-guide-driven approach to a streamlined, beginner-focused architecture. The Style Guide and Agent Guide Reference sections were removed entirely, with tutorial sections reorganized under a new "Tutorials For Beginners" label.

Changes

Cohort / File(s)	Summary
Documentation Rebuild Structure .cursor/commands/doc-rebuild.md	Restructured tutorials from enumerated multi-part sections (Foundations, Syntax, Machinery, Advanced) to beginner-focused subsections; removed Style Guide and Agent Guide Reference blocks entirely; simplified Example Programs header; minor header-level adjustments in Introduction section; net removal of 377 lines.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Regenerate Documentation #120 — Introduced the original .cursor/commands/doc-rebuild.md file; these changes substantially simplify and restructure the layout established in that PR by removing style/agent-guide sections and reorganizing tutorial structure.

Poem

🐰✨
Tutorial paths now clear and bright,
Beginner-focused, distilled just right,
Style guides fade, the clutter's gone,
Streamlined docs to carry on! 📚

🚥 Pre-merge checks | ✅ 1 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Refactor documentation generation framework' is vague and overly broad. The actual changes involve restructuring documentation content (tutorials, sections, style guides), not refactoring the underlying framework itself.	Consider a more specific title like 'Restructure documentation: consolidate tutorials and remove style guide' to accurately reflect the content reorganization changes.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.cursor/commands/doc-rebuild.md:
- Around line 18-20: The three indented bullets ("Buffer sequences — taken
straight from Boost.Asio and improved", "Stream concepts — _ReadStream_,
_WriteStream_, _ReadSource_, _WriteSink_, _BufferSource_, _BufferSink_", and
"Type-erased streams — `any_stream`, `any_read_stream`, `any_write_stream`, fast
compilation") are incorrectly indented; remove the leading two-space indentation
so they become top-level bullets under the "What This Library Does" section (or
alternatively, if you intend them as nested under item 2, convert the parent
item into an explicit list item first), ensuring the bullets follow standard
Markdown list indentation rules.

🧹 Nitpick comments (1)

.cursor/commands/doc-rebuild.md (1)

5-7: Consider separating header levels from list numbering.

The pattern ## 1. Introduction Page mixes markdown header syntax with numbered list formatting. While functional, this is non-standard. Consider either:

• Using pure headers: ## Introduction Page
• Or using a numbered list under a header rather than embedding numbers in header text

This would improve consistency with typical markdown conventions.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix list indentation to match markdown conventions.

The static analysis tool flags these lines for incorrect indentation. The bullets are indented by 2 spaces, but the parent item "What This Library Does" is not formatted as a list item—it's in the numbered requirement prose above.

Two options to fix:

1. If these should be nested under item 2, format item 2 as an explicit list item first
2. If these should be standalone, remove the indentation

🔧 Proposed fix: Remove indentation for standalone bullets

 2. **What This Library Does** (verbatim):
-  - Lazy coroutine tasks — `task<T>` with forward-propagating stop tokens and automatic cancellation
-  - Buffer sequences — taken straight from Boost.Asio and improved
-  - Stream concepts — _ReadStream_, _WriteStream_, _ReadSource_, _WriteSink_, _BufferSource_, _BufferSink_
-  - Type-erased streams — `any_stream`, `any_read_stream`, `any_write_stream`, fast compilation
+- Lazy coroutine tasks — `task<T>` with forward-propagating stop tokens and automatic cancellation
+- Buffer sequences — taken straight from Boost.Asio and improved
+- Stream concepts — _ReadStream_, _WriteStream_, _ReadSource_, _WriteSink_, _BufferSource_, _BufferSink_
+- Type-erased streams — `any_stream`, `any_read_stream`, `any_write_stream`, fast compilation

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

[warning] 18-18: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

[warning] 19-19: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

---

[warning] 20-20: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

🤖 Prompt for AI Agents

In @.cursor/commands/doc-rebuild.md around lines 18 - 20, The three indented
bullets ("Buffer sequences — taken straight from Boost.Asio and improved",
"Stream concepts — _ReadStream_, _WriteStream_, _ReadSource_, _WriteSink_,
_BufferSource_, _BufferSink_", and "Type-erased streams — `any_stream`,
`any_read_stream`, `any_write_stream`, fast compilation") are incorrectly
indented; remove the leading two-space indentation so they become top-level
bullets under the "What This Library Does" section (or alternatively, if you
intend them as nested under item 2, convert the parent item into an explicit
list item first), ensuring the bullets follow standard Markdown list indentation
rules.

[cppalliance-bot]

An automated preview of the documentation is available at https://122.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-02-02 04:58:22 UTC

[cppalliance-bot]

GCOVR code coverage report https://122.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://122.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://122.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-02-02 05:05:17 UTC