migrate to Zensical for documentation #357
Conversation
WalkthroughDocumentation tooling moved from MkDocs to Zensical; markdown preprocessing was moved into the justfile and docs/hooks.py removed. New/updated documentation pages and theme overrides were added; build/serve and ReadTheDocs commands adjusted; generated docs and trace.json added to gitignore. Changes
Sequence Diagram(s)sequenceDiagram
actor Dev
participant Justfile as Justfile
participant Preproc as Preprocessor
participant Zensical as Zensical
participant Site as Site
Dev->>Justfile: just build / just serve
Justfile->>Preproc: run copy/preprocess target
rect rgb(235,245,235)
Note over Preproc: Aggregate README/CHANGELOG/CONTRIBUTING\nConvert admonitions, rewrite links, normalize image paths
Preproc->>Preproc: emit docs/index.md, docs/changelog.md, docs/contributing.md
end
Justfile->>Zensical: invoke zensical build (clean)
Zensical->>Zensical: read config (.mkdocs.yml), theme, extensions
Zensical->>Site: generate site/
Site->>Dev: serve site
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (2)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)
🔇 Additional comments (1)
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: 3
🧹 Nitpick comments (1)
docs/clients/sublime-text.md (1)
55-55: Consider hyphenating compound adjective."Tool specific" should be "Tool-specific" when used as a compound adjective modifying "file".
Apply this diff:
-##### Tool specific file +##### Tool-specific fileBased on static analysis.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (21)
.gitignore(1 hunks).just/docs.just(1 hunks).mkdocs.yml(2 hunks).readthedocs.yaml(1 hunks)CONTRIBUTING.md(2 hunks)README.md(2 hunks)docs/.gitignore(1 hunks)docs/clients/index.md(1 hunks)docs/clients/neovim.md(3 hunks)docs/clients/sublime-text.md(3 hunks)docs/clients/vscode.md(1 hunks)docs/clients/zed.md(1 hunks)docs/configuration/index.md(7 hunks)docs/configuration/tagspecs.md(10 hunks)docs/hooks.py(0 hunks)docs/index.md(1 hunks)docs/installation.md(1 hunks)docs/overrides/partials/copyright.html(1 hunks)docs/stylesheets/extra.css(1 hunks)docs/versioning.md(1 hunks)pyproject.toml(1 hunks)
💤 Files with no reviewable changes (1)
- docs/hooks.py
🧰 Additional context used
🪛 LanguageTool
docs/index.md
[style] ~9-~9: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1602 characters long)
Context: ...e server for the Django web framework. !!! warning This project is in early s...
(EN_EXCESSIVE_EXCLAMATION)
docs/clients/sublime-text.md
[grammar] ~55-~55: Use a hyphen to join words.
Context: ... #### Configuration methods ##### Tool specific file Add a [tool.djls] secti...
(QB_NEW_EN_HYPHEN)
docs/configuration/tagspecs.md
[style] ~87-~87: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 3977 characters long)
Context: ...requires extra.choices) ## Examples !!! note All examples below use `djls....
(EN_EXCESSIVE_EXCLAMATION)
CONTRIBUTING.md
[style] ~15-~15: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...project and the various crates: - Main CLI interface (crates/djls/) - Co...
(ACRONYM_TAUTOLOGY)
[style] ~91-~91: This phrasing can be overused. Try elevating your writing with a more formal alternative.
Context: ... issues with newly added versions. If you want, you can also test only a specific Pyth...
(IF_YOU_WANT)
docs/installation.md
[style] ~37-~37: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1636 characters long)
Context: ... django-language-server djls serve ``` !!! note The server will automatically...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.18.1)
docs/clients/index.md
5-5: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/configuration/index.md
166-166: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/installation.md
40-40: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
85-85: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
99-99: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)
- GitHub Check: Python 3.14, Django main (ubuntu-latest)
- GitHub Check: Python 3.13, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.13, Django main (ubuntu-latest)
- GitHub Check: Python 3.11, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.11, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.10, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.12, Django main (ubuntu-latest)
- GitHub Check: Python 3.11, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.10, Django 5.1 (ubuntu-latest)
🔇 Additional comments (23)
docs/.gitignore (1)
1-3: LGTM!Appropriately ignoring generated documentation files to prevent build artifacts from entering version control.
docs/stylesheets/extra.css (1)
45-52: LGTM!CSS rules cleanly style the new copyright disclaimer section without conflicts. The margin resets ensure consistent spacing.
.gitignore (1)
193-195: LGTM!Updated comment and added trace.json to ignore rules, appropriately capturing build artifacts from the Zensical tooling migration.
.readthedocs.yaml (1)
14-15: LGTM with observation.The two-step build process correctly handles Zensical's output structure: build to the default location (
site/), then relocate to RTD's expected location (html/). This is a reasonable adaptation of the build workflow.Minor: If
just docs buildfails, the subsequentmvcommand will still execute and may produce confusing errors. Consider addingset -eat the top of the build commands section to fail fast, or use&&between commands to chain them conditionally. However, this is optional depending on RTD's error handling preferences.docs/clients/zed.md (1)
3-3: LGTM!Simplification of the Zed documentation appropriately removes complex dev-extension workflow in favor of the standard extension installation path. Users seeking advanced development instructions can consult the linked zed-django repository, which is the canonical source for extension-specific guidance.
Also applies to: 13-13
CONTRIBUTING.md (1)
43-95: LGTM!Code examples and instructions in the version update section are well-formatted and clear. The indentation and block structure improvements support readability and maintainability of the contribution guide.
docs/overrides/partials/copyright.html (1)
1-11: Verified: copyright partial is correctly integrated. Approve.Material for MkDocs automatically includes custom partials placed at
docs/overrides/partials/copyright.htmlin the footer—no explicit parent template reference needed. The path, Jinja syntax, and conditional logic are all correct. Withnavigation.footerenabled andcopyrightconfigured in.mkdocs.yml, the partial will render as expected.README.md (1)
29-30: Documentation restructuring looks clean. Removing leading "./" from image paths and consolidating content into dedicated guides aligns well with the migration. The new "Getting Started" section is clearer and properly delegates to external docs.Also applies to: 45-73
docs/clients/vscode.md (1)
13-13: Link target updated correctly. The reference to the installation guide now points to the dedicatedinstallation.mdfile, matching the new documentation structure.docs/index.md (1)
5-56: Content migration to embedded format is correct. Image paths properly relativized, links updated, and the admonition syntax is appropriate for the new documentation system. The structure mirrors README.md with proper formatting adjustments for the docs context.docs/installation.md (1)
1-120: Installation guide is comprehensive and well-structured. Covers all installation methods (uvx, uv, pipx, pip, standalone binaries, source build) with clear examples and platform-specific instructions. Code blocks within admonition/tab syntax appear to trigger static linting false positives (MD046), but formatting is correct for Material theme.docs/versioning.md (1)
1-21: Versioning documentation is clear and well-documented. Explains DjangoVer scheme concisely, clearly outlines the deprecate-for-two-releases policy with concrete examples, and provides transparency on breaking changes. Good addition to the documentation.docs/configuration/index.md (1)
7-7: Configuration documentation refined for clarity. Heading simplifications and the reformatted deprecation notice with proper admonition styling improve readability. Link paths correctly point to the new tagspecs documentation. MD046 flagging is a false positive within the warning admonition context.Also applies to: 74-74, 164-170
.mkdocs.yml (1)
1-82: Navigation restructuring and theme configuration are well-aligned with migration. The removal of include_markdown and addition of toc plugin supports the new content embedding strategy. Expanded nav hierarchy is logically organized with new dedicated guides. Theme features (footer, path breadcrumbs, instant loading) improve UX. Addition of custom_dir enables Zensical customizations.Verify that
docs/overrides/directory exists and contains any necessary custom HTML/CSS overrides for the Zensical theme customization.docs/clients/sublime-text.md (2)
5-8: LGTM: Improved requirements clarity.The bullet-point format with specific version requirements and clear installation instructions enhances readability.
14-40: LGTM: Excellent addition of concrete configuration example.The JSON code block provides clear, actionable guidance with helpful notes about path configuration for different installation methods.
.just/docs.just (2)
84-95: LGTM: Clean integration of new preprocessing step.The
copydependency correctly ensures documentation is generated before building or serving. The switch tozensicalaligns with the PR's migration objective.
10-77: Patterns are syntactically and logically sound—verify output against your content.The shell/awk/sed patterns are valid:
- Awk state machines correctly track admonitions and cog blocks with proper flag transitions
- Sed link patterns properly discriminate relative links from URLs/anchors/absolute paths using
[^h#:/]exclusion- All source files exist (CHANGELOG.md, CONTRIBUTING.md, README.md) and docs/ directory is present
Since the
justcommand is unavailable in the sandbox, I cannot execute the transformations to verify output. However, the code appears correct upon static analysis. To be confident, manually runjust --justfile .just/docs.just copyin your local environment and inspect the generated files (docs/changelog.md, docs/contributing.md, docs/index.md) to confirm:
- Admonitions convert correctly (> [!NOTE] → !!! note)
- Relative links rewrite to GitHub URLs as expected
- No unwanted content is filtered
docs/clients/neovim.md (2)
10-53: LGTM: Excellent documentation restructure.The split between "With nvim-lspconfig" and "Without nvim-lspconfig" paths provides clear guidance for different user setups. The concrete examples for both inline and dedicated config files are especially helpful.
71-123: LGTM: Sophisticated filetype detection with helpful caveats.The directory tree walking logic for Django project detection is well-implemented and documented. The note about naive TOML parsing (line 96-97) appropriately manages user expectations while providing a functional solution.
docs/configuration/tagspecs.md (3)
1-1: LGTM: Consistent documentation structure.The markdown H1 header and sentence-case headings align with modern documentation standards. Renaming "Common Patterns" to "Examples" is more direct and user-friendly.
Also applies to: 68-68, 74-74, 86-86, 158-158
179-179: LGTM: Correct cross-reference update.The link correctly points to the new dedicated versioning document, aligning with the documentation restructuring in this PR.
209-221: LGTM: Improved document flow.Moving the argument type mapping before the migration examples improves readability—users now see the reference material before applying it in examples.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.readthedocs.yaml(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)
- GitHub Check: Python 3.14, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.14, Django main (ubuntu-latest)
- GitHub Check: Python 3.11, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.14, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.12, Django main (ubuntu-latest)
- GitHub Check: Python 3.14, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.13, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 6.0a1 (ubuntu-latest)
- GitHub Check: Python 3.10, Django 5.1 (ubuntu-latest)
- GitHub Check: Python 3.11, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.12, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.10, Django 5.2 (ubuntu-latest)
- GitHub Check: Python 3.11, Django 4.2 (ubuntu-latest)
- GitHub Check: Python 3.10, Django 4.2 (ubuntu-latest)
🔇 Additional comments (1)
.readthedocs.yaml (1)
18-19: Clarify mkdocs configuration status during migration.The mkdocs configuration section (lines 18–19) remains in the file, but according to the PR objective, the project is migrating from MkDocs to Zensical. Should this section be removed, updated, or left in place for backwards compatibility?
Summary by CodeRabbit