formatting
This commit is contained in:
John Lancaster
@@ -6,10 +6,10 @@ Use this reference when your docs include API surfaces, function/class documenta
|
||||
|
||||
mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.
|
||||
|
||||
Primary docs:
|
||||
- mkdocstrings home: https://mkdocstrings.github.io/
|
||||
- mkdocstrings Python handler: https://mkdocstrings.github.io/python/
|
||||
- Griffe (Python parsing engine): https://mkdocstrings.github.io/griffe/
|
||||
!!! info "Primary docs"
|
||||
- [mkdocstrings home](https://mkdocstrings.github.io/)
|
||||
- [mkdocstrings Python handler](https://mkdocstrings.github.io/python/)
|
||||
- [Griffe Python parsing engine](https://mkdocstrings.github.io/griffe/)
|
||||
|
||||
## When to Use It
|
||||
|
||||
@@ -32,13 +32,13 @@ Primary docs:
|
||||
3. Create one API index page per package/domain.
|
||||
4. Expand coverage gradually from high-value modules first.
|
||||
|
||||
General reference examples:
|
||||
- Zensical docs home and setup entry point: https://zensical.org/docs/
|
||||
- Zensical code blocks and authoring patterns: https://zensical.org/docs/authoring/code-blocks/
|
||||
- Zensical customization overview: https://zensical.org/docs/customization/
|
||||
!!! info "General reference examples"
|
||||
- [Zensical docs home and setup entry point](https://zensical.org/docs/)
|
||||
- [Zensical code blocks and authoring patterns](https://zensical.org/docs/authoring/code-blocks/)
|
||||
- [Zensical customization overview](https://zensical.org/docs/customization/)
|
||||
|
||||
Compatibility note:
|
||||
- Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
|
||||
!!! note "Compatibility"
|
||||
Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
|
||||
|
||||
## Authoring Guidance for Docstrings
|
||||
|
||||
|
||||
@@ -13,9 +13,9 @@ Recommended top-level model:
|
||||
3. Reference (API, config, command catalog)
|
||||
4. Troubleshoot (symptoms, diagnostics, fixes)
|
||||
|
||||
References:
|
||||
- Diataxis framework: https://diataxis.fr/
|
||||
- Divio documentation system: https://documentation.divio.com/
|
||||
!!! info "IA references"
|
||||
- [Diataxis framework](https://diataxis.fr/)
|
||||
- [Divio documentation system](https://documentation.divio.com/)
|
||||
|
||||
## Progressive Discoverability Pattern
|
||||
|
||||
@@ -47,11 +47,11 @@ Keep deep details in dedicated reference pages and link to them from task pages
|
||||
3. Place high-frequency tasks near the top.
|
||||
4. Keep section depth shallow where possible.
|
||||
|
||||
Relevant Zensical configuration docs:
|
||||
- Navigation: https://zensical.org/docs/setup/navigation/
|
||||
- Search: https://zensical.org/docs/setup/search/
|
||||
- Header: https://zensical.org/docs/setup/header/
|
||||
- Footer: https://zensical.org/docs/setup/footer/
|
||||
!!! info "Relevant Zensical configuration docs"
|
||||
- [Navigation setup](https://zensical.org/docs/setup/navigation/)
|
||||
- [Search setup](https://zensical.org/docs/setup/search/)
|
||||
- [Header setup](https://zensical.org/docs/setup/header/)
|
||||
- [Footer setup](https://zensical.org/docs/setup/footer/)
|
||||
|
||||
## Link Strategy
|
||||
|
||||
|
||||
@@ -10,10 +10,10 @@ Use this reference when writing or reviewing docs for clarity, correctness, and
|
||||
4. Make examples executable and verifiable.
|
||||
5. Prefer precise language over marketing language.
|
||||
|
||||
Primary references:
|
||||
- Diataxis: https://diataxis.fr/
|
||||
- Divio documentation system: https://documentation.divio.com/
|
||||
- Write the Docs guide: https://www.writethedocs.org/guide/
|
||||
!!! info "Primary references"
|
||||
- [Diataxis](https://diataxis.fr/)
|
||||
- [Divio documentation system](https://documentation.divio.com/)
|
||||
- [Write the Docs guide](https://www.writethedocs.org/guide/)
|
||||
|
||||
## Style and Readability
|
||||
|
||||
@@ -22,10 +22,10 @@ Primary references:
|
||||
- Prefer active voice and imperative instructions for task pages.
|
||||
- Add notes/warnings only for high-impact caveats.
|
||||
|
||||
Source links:
|
||||
- Google developer style: https://developers.google.com/style
|
||||
- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
|
||||
- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
|
||||
!!! info "Style sources"
|
||||
- [Google developer style](https://developers.google.com/style)
|
||||
- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
|
||||
- [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
|
||||
|
||||
## Task Page Quality Pattern
|
||||
|
||||
|
||||
@@ -4,40 +4,43 @@ Use this index to load only the source references needed for the current task.
|
||||
|
||||
## Zensical Official Docs
|
||||
|
||||
- New project scaffolding (`uv run zensical new`): https://zensical.org/docs/
|
||||
- Home: https://zensical.org/docs/
|
||||
- Setup basics: https://zensical.org/docs/setup/basics/
|
||||
- Navigation setup: https://zensical.org/docs/setup/navigation/
|
||||
- Header setup and announcement bar: https://zensical.org/docs/setup/header/
|
||||
- Footer setup: https://zensical.org/docs/setup/footer/
|
||||
- Repository and content actions: https://zensical.org/docs/setup/repository/
|
||||
- Search setup: https://zensical.org/docs/setup/search/
|
||||
- Customization overview: https://zensical.org/docs/customization/
|
||||
- Additional CSS: https://zensical.org/docs/customization/#additional-css
|
||||
- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
|
||||
- Theme extension and overrides: https://zensical.org/docs/customization/#extending-the-theme
|
||||
- Language setup: https://zensical.org/docs/setup/language/
|
||||
- Logo and icons: https://zensical.org/docs/setup/logo-and-icons/
|
||||
- Code blocks and annotations: https://zensical.org/docs/authoring/code-blocks/
|
||||
- Content tabs: https://zensical.org/docs/authoring/content-tabs/
|
||||
- Footnotes: https://zensical.org/docs/authoring/footnotes/
|
||||
- Tooltips: https://zensical.org/docs/authoring/tooltips/
|
||||
!!! info "Zensical official docs"
|
||||
- [New project scaffolding](https://zensical.org/docs/) for `uv run zensical new`.
|
||||
- [Home](https://zensical.org/docs/)
|
||||
- [Setup basics](https://zensical.org/docs/setup/basics/)
|
||||
- [Navigation setup](https://zensical.org/docs/setup/navigation/)
|
||||
- [Header setup and announcement bar](https://zensical.org/docs/setup/header/)
|
||||
- [Footer setup](https://zensical.org/docs/setup/footer/)
|
||||
- [Repository and content actions](https://zensical.org/docs/setup/repository/)
|
||||
- [Search setup](https://zensical.org/docs/setup/search/)
|
||||
- [Customization overview](https://zensical.org/docs/customization/)
|
||||
- [Additional CSS](https://zensical.org/docs/customization/#additional-css)
|
||||
- [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
|
||||
- [Theme extension and overrides](https://zensical.org/docs/customization/#extending-the-theme)
|
||||
- [Language setup](https://zensical.org/docs/setup/language/)
|
||||
- [Logo and icons](https://zensical.org/docs/setup/logo-and-icons/)
|
||||
- [Code blocks and annotations](https://zensical.org/docs/authoring/code-blocks/)
|
||||
- [Content tabs](https://zensical.org/docs/authoring/content-tabs/)
|
||||
- [Footnotes](https://zensical.org/docs/authoring/footnotes/)
|
||||
- [Tooltips](https://zensical.org/docs/authoring/tooltips/)
|
||||
|
||||
## Adjacent Documentation Quality Sources
|
||||
|
||||
- Divio documentation system: https://documentation.divio.com/
|
||||
- Write the Docs guide: https://www.writethedocs.org/guide/
|
||||
- Google developer documentation style guide: https://developers.google.com/style
|
||||
- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
|
||||
- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
|
||||
- Diataxis framework: https://diataxis.fr/
|
||||
!!! info "Documentation quality sources"
|
||||
- [Divio documentation system](https://documentation.divio.com/)
|
||||
- [Write the Docs guide](https://www.writethedocs.org/guide/)
|
||||
- [Google developer documentation style guide](https://developers.google.com/style)
|
||||
- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
|
||||
- [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
|
||||
- [Diataxis framework](https://diataxis.fr/)
|
||||
|
||||
## Related Tooling References
|
||||
|
||||
- Markdown guide: https://www.markdownguide.org/
|
||||
- Zensical setup and configuration entry point: https://zensical.org/docs/
|
||||
- Zensical customization reference: https://zensical.org/docs/customization/
|
||||
- mkdocstrings: https://mkdocstrings.github.io/
|
||||
!!! info "Related tooling"
|
||||
- [Markdown guide](https://www.markdownguide.org/)
|
||||
- [Zensical setup and configuration entry point](https://zensical.org/docs/)
|
||||
- [Zensical customization reference](https://zensical.org/docs/customization/)
|
||||
- [mkdocstrings](https://mkdocstrings.github.io/)
|
||||
|
||||
## Skill-Specific Deep Dives
|
||||
|
||||
|
||||
@@ -15,11 +15,12 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
|
||||
|
||||
## Key Zensical Customization Surfaces
|
||||
|
||||
- Customization overview: https://zensical.org/docs/customization/
|
||||
- Additional CSS: https://zensical.org/docs/customization/#additional-css
|
||||
- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
|
||||
- Extending the theme: https://zensical.org/docs/customization/#extending-the-theme
|
||||
- Logo and icons setup: https://zensical.org/docs/setup/logo-and-icons/
|
||||
!!! info "Zensical sources"
|
||||
- [Customization overview](https://zensical.org/docs/customization/)
|
||||
- [Additional CSS](https://zensical.org/docs/customization/#additional-css)
|
||||
- [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
|
||||
- [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
|
||||
- [Logo and icons setup](https://zensical.org/docs/setup/logo-and-icons/)
|
||||
|
||||
## Colors and Accessibility
|
||||
|
||||
@@ -27,21 +28,22 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
|
||||
- Keep contrast high for body text, code blocks, and nav labels.
|
||||
- Test color changes on mobile and desktop, including search highlights and active nav states.
|
||||
|
||||
General references:
|
||||
- Material design color guidance: https://m3.material.io/styles/color
|
||||
- WCAG overview: https://www.w3.org/WAI/standards-guidelines/wcag/
|
||||
!!! info "General references"
|
||||
- [Material Design color guidance](https://m3.material.io/styles/color)
|
||||
- [WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/)
|
||||
|
||||
## Icons: Selection and Search Landing Pages
|
||||
|
||||
If your theme supports icon sets through your docs stack, these search portals are useful:
|
||||
|
||||
- Material Symbols search: https://fonts.google.com/icons
|
||||
- Font Awesome icons search: https://fontawesome.com/search
|
||||
- Simple Icons search: https://simpleicons.org/
|
||||
- Iconify icon set search: https://icon-sets.iconify.design/
|
||||
- Lucide icons: https://lucide.dev/icons/
|
||||
- [Material Symbols search](https://fonts.google.com/icons)
|
||||
- [Font Awesome icons search](https://fontawesome.com/search)
|
||||
- [Simple Icons search](https://simpleicons.org/)
|
||||
- [Iconify icon set search](https://icon-sets.iconify.design/)
|
||||
- [Lucide icons](https://lucide.dev/icons/)
|
||||
|
||||
Tip: pick one primary icon family for navigation and status icons, then document naming conventions.
|
||||
!!! tip "Icon family consistency"
|
||||
Pick one primary icon family for navigation and status icons, then document naming conventions.
|
||||
|
||||
## Extending the Theme Safely
|
||||
|
||||
|
||||
@@ -21,8 +21,8 @@ Always start a new docs project with `uv run zensical new`.
|
||||
- `navigation.top`: shows a back-to-top affordance.
|
||||
- `navigation.tracking`: keeps URL anchors in sync with active section.
|
||||
|
||||
Source links:
|
||||
- https://zensical.org/docs/setup/navigation/
|
||||
!!! info "Source links"
|
||||
- [Zensical navigation setup](https://zensical.org/docs/setup/navigation/)
|
||||
|
||||
### Code-Heavy Documentation
|
||||
|
||||
@@ -32,9 +32,9 @@ Source links:
|
||||
- Prefer mkdocstrings for generated API reference pages when documenting Python code.
|
||||
- Keep generated API pages linked from hand-authored task and concept docs.
|
||||
|
||||
Source links:
|
||||
- https://zensical.org/docs/authoring/code-blocks/
|
||||
- https://mkdocstrings.github.io/
|
||||
!!! info "Source links"
|
||||
- [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
|
||||
- [mkdocstrings](https://mkdocstrings.github.io/)
|
||||
|
||||
### Cross-Page UX Consistency
|
||||
|
||||
@@ -42,19 +42,19 @@ Source links:
|
||||
- `content.tooltips`: improves tooltip behavior for links.
|
||||
- `content.footnote.tooltips`: inline footnote previews.
|
||||
|
||||
Source links:
|
||||
- https://zensical.org/docs/authoring/content-tabs/
|
||||
- https://zensical.org/docs/authoring/tooltips/
|
||||
- https://zensical.org/docs/authoring/footnotes/
|
||||
!!! info "Source links"
|
||||
- [Zensical content tabs](https://zensical.org/docs/authoring/content-tabs/)
|
||||
- [Zensical tooltips](https://zensical.org/docs/authoring/tooltips/)
|
||||
- [Zensical footnotes](https://zensical.org/docs/authoring/footnotes/)
|
||||
|
||||
### Search and Content Actions
|
||||
|
||||
- `search.highlight`: highlights matches after search navigation.
|
||||
- `content.action.edit` and `content.action.view` (if repository integration is configured).
|
||||
|
||||
Source links:
|
||||
- https://zensical.org/docs/setup/search/
|
||||
- https://zensical.org/docs/setup/repository/
|
||||
!!! info "Source links"
|
||||
- [Zensical search setup](https://zensical.org/docs/setup/search/)
|
||||
- [Zensical repository setup](https://zensical.org/docs/setup/repository/)
|
||||
|
||||
## Styling and Extensibility
|
||||
|
||||
@@ -64,11 +64,11 @@ Use site-level customization when docs need stronger visual affordances.
|
||||
- `extra_javascript`: add behavior enhancements.
|
||||
- Theme override directory (`custom_dir`) for template-level changes.
|
||||
|
||||
Source links:
|
||||
- https://zensical.org/docs/customization/
|
||||
- https://zensical.org/docs/customization/#additional-css
|
||||
- https://zensical.org/docs/customization/#additional-javascript
|
||||
- https://zensical.org/docs/customization/#extending-the-theme
|
||||
!!! info "Source links"
|
||||
- [Zensical customization overview](https://zensical.org/docs/customization/)
|
||||
- [Additional CSS](https://zensical.org/docs/customization/#additional-css)
|
||||
- [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
|
||||
- [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
|
||||
|
||||
## Practical Feature Selection Rules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user