docs(docs): clean up public documentation (#34) - #153
Conversation
- Make README and contribution entry points accurate and navigable - Add an offline Markdown structure and link-policy contract test - Remove generated-site premises from the public roadmap and build docs
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe pull request establishes ChangesPublic documentation cleanup
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
CONTRIBUTING.md (1)
11-11: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd language identifiers to fenced code blocks.
These fences produce
MD040warnings. Usetextfor diagrams, templates, and procedural examples where no executable language applies.Also applies to: 52-52, 62-62, 125-125, 187-187
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CONTRIBUTING.md` at line 11, Update every fenced code block in CONTRIBUTING.md, including the referenced occurrences, to include an appropriate language identifier; use text for diagrams, templates, and non-executable procedural examples to eliminate MD040 warnings.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 37-45: Update the task-start requirement in the numbered workflow
of CONTRIBUTING.md to require reading the full target GitHub Issue, applicable
issue-breakdown entry, referenced design sections, related ADRs, and the full
CONTRIBUTING.md workflow and TDD steps before implementation begins; retain the
existing issue-existence confirmation.
In `@docs/06_build_test_packaging.md`:
- Around line 399-401: Add the required command `python3
tests/docs/test_public_documentation.py -v` to mandatory CI validation or
register an equivalent CTest, ensuring the public documentation contract runs in
the existing validation workflow alongside current CTest and CI Python suites.
In `@docs/07_issue_breakdown.md`:
- Around line 631-632: Update the “Implementation targets” entry in the roadmap
to list every target as an exact path rather than category descriptions,
including README.md, CONTRIBUTING.md, AGENTS.md, docs/development_workflow.md,
docs/00_overview.md, docs/08_contract_registry.md,
docs/06_build_test_packaging.md, the compatibility workflow pointer,
public-document navigation files, tests/docs/test_public_documentation.py, and
this roadmap file.
In `@tests/docs/test_public_documentation.py`:
- Around line 114-116: Update the documentation line-processing logic around
validate_destination so four-space-indented list continuation lines are not
unconditionally discarded; parse whether the indentation belongs to a list
continuation or reject ambiguous indented link syntax before skipping. Add a
regression test covering a list item followed by an indented link and ensure the
link is validated.
---
Nitpick comments:
In `@CONTRIBUTING.md`:
- Line 11: Update every fenced code block in CONTRIBUTING.md, including the
referenced occurrences, to include an appropriate language identifier; use text
for diagrams, templates, and non-executable procedural examples to eliminate
MD040 warnings.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7e9e94d8-ae5b-4d8d-bb34-878ebe07ef92
📒 Files selected for processing (9)
AGENTS.mdCONTRIBUTING.mdREADME.mddocs/00_overview.mddocs/06_build_test_packaging.mddocs/07_issue_breakdown.mddocs/08_contract_registry.mddocs/development_workflow.mdtests/docs/test_public_documentation.py
- Reject multiline candidates with forbidden label or alt syntax - Add review-driven regression fixtures for escaped and nested forms - Validate the offline documentation contract from repository and external working directories
- Cover every frozen ASCII-whitespace boundary for raw link tags - Add review-driven regression fixtures for vertical-tab anchors and images - Validate the offline documentation contract from repository and external working directories
- Split only CRLF, CR, and LF boundaries in the offline scanner - Add review-driven regression coverage for control-separator prefixes - Validate the documentation contract from repository and external directories
- Recognize CRLF, CR, and LF boundaries in multiline link checks - Add review-driven regression coverage for all physical line endings - Validate the documentation contract from repository and external directories
|
|
Disposition: not applicable for Issue #34. The requested broad Python docstring coverage is outside the frozen Markdown-only scope; Issue #34 explicitly excludes broad C++ comment and Python docstring work. Corrective commit: not applicable (no change required). Sol confirmed this disposition at head Source: #153 (comment) |
|
Disposition: not applicable for Issue #34. MD040 fence-language identifiers are not an acceptance requirement; the frozen grammar explicitly allows an optional fence info string. Corrective commit: not applicable (no change required). Sol confirmed this disposition at head Source: #153 (review) |
1 participant
Summary
Closes #34
CONTRIBUTING.mdthe canonical development workflow and retain the former path as an exact compatibility pointerRequirements
Reference requirement IDs from docs/01_requirements.md (F/N/C/P/X): N/A — this PR changes documentation navigation and contributor guidance, not product behavior.
Contract Registry
Affected contract-registry row(s) (docs/08_contract_registry.md) with their status transition
(
Contract/Implementation/none), orN/Aif no contract is touched:N/A — no public API, wire, identifier, or compatibility contract changes.
Frozen Issue Checklist
README.md: replace the obsolete pre-development status; show the existing Linux and Windows configure/build/test preset commands; linkexamples/cpp/quickstart.cppandexamples/python/quickstart.py; summarize the roles ofStorageNode,ParamStore, andParamCachewith a link todocs/02_architecture.md; and add only the trackedCIworkflow status badgeCONTRIBUTING.mdthe single canonical development workflow; replacedocs/development_workflow.mdwith a short compatibility pointer and update repository-owned links to the canonical filedocs/00_overview.md,docs/06_build_test_packaging.md, and the#34/#35roadmap entries indocs/07_issue_breakdown.mdwith the Markdown-only documentation policytests/docs/test_public_documentation.py; it must enforce the exact machine-checkable content assertions and repository-owned Markdown link grammar below without network accessAcceptance Criteria Verification
python3 tests/docs/test_public_documentation.py -v(cd /tmp && python3 /home/hayate/git/sitos/tests/docs/test_public_documentation.py -v)git diff --checkREADME.md,CONTRIBUTING.md, anddocs/development_workflow.mdinspected for headings, lists, code fences, links, and presentationCIandPython wheelsPR jobsRED-phase Evidence
python3 tests/docs/test_public_documentation.py -vPublicDocumentationTest.test_contributing_contractCONTRIBUTING.md; its README and legacy workflow path also violated the frozen documentation contractFileNotFoundError: [Errno 2] No such file or directory: '/home/hayate/git/sitos/CONTRIBUTING.md'This is pre-implementation compile/contract RED, not behavioral RED. Behavioral RED is N/A because the frozen scope changes documentation content and link contracts only.
ADR Needed?
An ADR is required when docs/10_adr_process.md §6 applies. §6 includes introducing a second
surface that overlaps an existing contract-registry row (registry Rule 2).
No dependency, generated-documentation architecture, hosting, build behavior, protocol, or public API decision is introduced.
Owner Merge Authorization
Complete this section only after the owner authorizes this exact PR head. Leave the status as
Pendingwhen opening or updating the PR.Authorization is one-time, expires after a new commit or new blocking finding, and never enables
auto-merge.