Split docs into user and developer wikis#2588
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request restructures the documentation site to be audience-first, introducing a 'User Wiki' and a 'Developer Wiki' as top-level entry points. It updates the navigation in mkdocs.yml, adds landing pages under Docs/Wiki, introduces several Architecture Decision Records (ADRs), and updates the sync script and test configurations. Feedback from the reviewer correctly identifies that the Getting_Started and Overview directories are referenced in the navigation but are missing from the public site folder list in Docs_Site_Guide.md, the sync script refresh_docs_published.sh, and the test setup in conftest.py, which could lead to broken links or build failures.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| - `Docs/Evals` | ||
| - `Docs/User_Guides` |
There was a problem hiding this comment.
The folders Docs/Getting_Started and Docs/Overview are referenced in the navigation configuration of Docs/mkdocs.yml and linked in the new wikis, but they are not listed here under the folders included on the public site. Please update this list to include them.
| preserve_and_copy "$SRC_DIR/API-related" "$DEST_DIR/API-related" | ||
|
|
||
| # Audience wiki landing pages | ||
| preserve_and_copy "$SRC_DIR/Wiki" "$DEST_DIR/Wiki" |
There was a problem hiding this comment.
The folders Getting_Started and Overview are active parts of the documentation site navigation and are linked from the new wikis, but they are currently omitted from the sync process. This will cause broken links or build failures in clean environments where Docs/Published is generated from scratch. Please add copy commands for these folders.
| preserve_and_copy "$SRC_DIR/Wiki" "$DEST_DIR/Wiki" | |
| preserve_and_copy "$SRC_DIR/Wiki" "$DEST_DIR/Wiki" | |
| preserve_and_copy "$SRC_DIR/Getting_Started" "$DEST_DIR/Getting_Started" | |
| preserve_and_copy "$SRC_DIR/Overview" "$DEST_DIR/Overview" |
|
|
||
| _preserve_and_copy(src_dir / "API-related", dest_dir / "API-related") | ||
| _preserve_and_copy(src_dir / "Code_Documentation", dest_dir / "Code_Documentation") | ||
| _preserve_and_copy(src_dir / "Wiki", dest_dir / "Wiki") |
There was a problem hiding this comment.
Similarly to the refresh script, the test setup in conftest.py does not copy the Getting_Started and Overview folders to the temporary test destination directory. This can cause tests that verify documentation structure or build the site to fail. Please add copy calls for these folders.
| _preserve_and_copy(src_dir / "Wiki", dest_dir / "Wiki") | |
| _preserve_and_copy(src_dir / "Wiki", dest_dir / "Wiki") | |
| _preserve_and_copy(src_dir / "Getting_Started", dest_dir / "Getting_Started") | |
| _preserve_and_copy(src_dir / "Overview", dest_dir / "Overview") |
PR Summary by QodoSplit docs into user and developer wiki entry points
AI Description
Diagram
High-Level Assessment
Files changed (62)
|
Code Review by Qodo
Context used✅ Compliance rules (platform):
74 rules 1. _read() missing docstring
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| def _read(relative_path: str) -> str: | ||
| return (REPO_ROOT / relative_path).read_text(encoding="utf-8") |
There was a problem hiding this comment.
1. _read() missing docstring 📘 Rule violation ✧ Quality
The new helper function _read() has no function docstring, violating the requirement that all functions in changed Python code include docstrings. Missing docstrings reduce maintainability and make test helpers harder to understand and reuse safely.
Agent Prompt
## Issue description
`tldw_Server_API/tests/Docs/test_docs_audience_wikis.py` introduces `_read()` without a docstring.
## Issue Context
Compliance requires docstrings for all functions in new/changed Python files.
## Fix Focus Areas
- tldw_Server_API/tests/Docs/test_docs_audience_wikis.py[13-15]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| def test_docs_audience_wiki_source_and_published_pages_exist() -> None: | ||
| """The docs site should expose source and generated audience wiki pages.""" | ||
| for relative_path in ( | ||
| "Docs/Wiki/index.md", | ||
| "Docs/Wiki/User_Wiki.md", | ||
| "Docs/Wiki/Developer_Wiki.md", | ||
| "Docs/Published/Wiki/index.md", | ||
| "Docs/Published/Wiki/User_Wiki.md", | ||
| "Docs/Published/Wiki/Developer_Wiki.md", | ||
| ): | ||
| _require((REPO_ROOT / relative_path).is_file(), f"Missing {relative_path}") | ||
|
|
||
|
|
||
| def test_mkdocs_nav_exposes_audience_wikis() -> None: | ||
| """MkDocs navigation should make the audience split visible at top level.""" | ||
| mkdocs_text = _read("Docs/mkdocs.yml") | ||
|
|
||
| _require("Home: Wiki/index.md" in mkdocs_text, "MkDocs nav should use Wiki home") | ||
| _require("User Wiki:" in mkdocs_text, "MkDocs nav should expose User Wiki") | ||
| _require("Developer Wiki:" in mkdocs_text, "MkDocs nav should expose Developer Wiki") | ||
| _require( | ||
| "Start Here: Wiki/User_Wiki.md" in mkdocs_text, | ||
| "User Wiki nav should start at the user wiki page", | ||
| ) | ||
| _require( | ||
| "Start Here: Wiki/Developer_Wiki.md" in mkdocs_text, | ||
| "Developer Wiki nav should start at the developer wiki page", | ||
| ) | ||
|
|
||
|
|
||
| def test_readme_points_users_and_contributors_to_wikis() -> None: | ||
| """README should route readers to the right documentation audience entry.""" | ||
| readme_text = _read("README.md") | ||
|
|
||
| _require("Docs/Wiki/User_Wiki.md" in readme_text, "README should link User Wiki") | ||
| _require( | ||
| "Docs/Wiki/Developer_Wiki.md" in readme_text, | ||
| "README should link Developer Wiki", | ||
| ) | ||
| _require("User Wiki" in readme_text, "README should label the User Wiki") | ||
| _require("Developer Wiki" in readme_text, "README should label the Developer Wiki") |
There was a problem hiding this comment.
2. Tests missing pytest marker 📘 Rule violation ▣ Testability
The newly added docs contract tests are not decorated with an allowed pytest marker (e.g., @pytest.mark.unit), violating the project requirement that each test has exactly one accepted marker. This can break test selection and CI categorization.
Agent Prompt
## Issue description
New tests in `tldw_Server_API/tests/Docs/test_docs_audience_wikis.py` do not have any of the required pytest markers.
## Issue Context
Project compliance requires each test to be decorated with exactly one accepted marker (`unit`, `integration`, `external_api`, or `local_llm_service`). Existing Docs contract tests in the suite use `@pytest.mark.unit`.
## Fix Focus Areas
- tldw_Server_API/tests/Docs/test_docs_audience_wikis.py[23-63]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
|
||
| ## Shared References | ||
|
|
||
| - [Feature status](../Overview/Feature_Status.md) |
There was a problem hiding this comment.
3. Dead feature status link 🐞 Bug ≡ Correctness
Docs/Wiki/index.md links to ../Overview/Feature_Status.md, which resolves to Docs/Overview/Feature_Status.md when browsing the repo, but that path does not exist. This produces a 404/dead link for readers using the new wiki landing page directly in GitHub.
Agent Prompt
### Issue description
`Docs/Wiki/index.md` includes a relative link to `../Overview/Feature_Status.md`. In the repository, that resolves to `Docs/Overview/Feature_Status.md`, which does not exist (the Feature Status page currently lives under `Docs/Published/Overview/Feature_Status.md`). This makes the new Wiki landing page contain a dead link when viewed in GitHub.
### Issue Context
MkDocs builds from `Docs/Published` (`docs_dir: Published`), so the same markdown link works in the rendered docs site because it resolves to `Docs/Published/Overview/Feature_Status.md`. But the repo-facing source wiki page should also have valid links.
### Fix Focus Areas
- Docs/Wiki/index.md[28-33]
- Helper_Scripts/refresh_docs_published.sh[59-95]
### Suggested fix
Implement one of the following:
1) **Preferred (keeps relative links working everywhere):** Add `Docs/Overview/Feature_Status.md` (move or copy the canonical content there), and update the refresh script to also copy `Docs/Overview` into `Docs/Published/Overview` so source and published stay in sync.
2) If you do not want a source `Docs/Overview` tree: change the link in `Docs/Wiki/index.md` to an absolute URL (e.g., the published site URL or a GitHub URL), accepting that it won’t be a local relative link in MkDocs.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
1 participant
Summary
Docs/Wiki.Docs/Publishedchurn limited to the files required by the new nav.Test Plan
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 /Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m pytest -q -p pytest_asyncio.plugin tldw_Server_API/tests/Docs— 120 passed/Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m mkdocs build -f Docs/mkdocs.yml— exit 0; existing repo-wide docs warnings remain/Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python Helper_Scripts/docs/check_public_private_boundary.py/Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python Helper_Scripts/docs/check_readme_docs_path_hygiene.py/Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python Helper_Scripts/docs/check_top_guides_docs_path_hygiene.py/Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m bandit -r tldw_Server_API/tests/Docs/test_docs_audience_wikis.py tldw_Server_API/tests/Docs/conftest.py -f json -o /tmp/bandit_task_12119_docs.json— zero findingsMerge Note
Summary by cubic
Split the docs into audience-first User and Developer wikis and made them the new Home for the published site. Updated navigation, refresh pipeline, CI checks, tests, and README links; also published an Architecture overview, ADRs, and a Data Flow Atlas for contributors.
Docs/Wikilanding pages (User Wiki, Developer Wiki), published underDocs/Published/Wiki, and setWiki/index.mdas Home inDocs/mkdocs.yml.Wiki/,Architecture.md, andADR/; CI now verifiesDocs/Published/Wiki,Docs/Published/ADR, andDocs/Published/Architecture.md.Docs/Wiki/User_Wiki.mdandDocs/Wiki/Developer_Wiki.md.Architecture.md, ADR set (+inventory/README), and the Data Flow Atlas.Written for commit 74a7937. Summary will update on new commits.