Documentation¶

This guide explains how documentation is set up in this Python package template, including Zensical configuration, API reference generation, and best practices for writing docs.

Overview¶

The template uses Zensical for documentation, featuring:

Modern, responsive theme: Built-in dark mode support
API Documentation: Auto-generated from docstrings
Multi-page Structure: Organized user guides and developer docs
Search: Built-in search
Customizable: Theme palette, fonts, and layout via zensical.toml

Zensical Configuration¶

Basic Setup (`zensical.toml`)¶

# ============================================================================
#
# The configuration produced by default is meant to highlight the features
# that Zensical provides and to serve as a starting point for your own
# projects.
#
# ============================================================================

[project]

# The site_name is shown in the page header and the browser window title
#
# Read more: https://zensical.org/docs/setup/basics/#site_name
site_name = "Python Package Template Documentation"

# The site_description is included in the HTML head and should contain a
# meaningful description of the site content for use by search engines.
#
# Read more: https://zensical.org/docs/setup/basics/#site_description
site_description = "A GitHub template repository for a Python package."

# The site_author attribute. This is used in the HTML head element.
#
# Read more: https://zensical.org/docs/setup/basics/#site_author
site_author = "Isaac C. F. Wong"

# The site_url is the canonical URL for your site. When building online
# documentation you should set this.
# Read more: https://zensical.org/docs/setup/basics/#site_url
#site_url = "https://www.example.com/"

nav = [
  { "Get Started" = "index.md" },
  { "API" = [
    { "Overview" = "api/index.md" },
    { "Hello World" = "api/hello_world.md" },
    { "Utility" = [
      { "Overview" = "api/utils/index.md" },
      { "Logging" = "api/utils/log.md" },
    ] },
  ] },
  { "Contributing" = "contributing.md" },
  { "Security" = "security.md" },
  { "Template documentation" = [
    { "Overview" = "template_documentation/index.md" },
    { "Using this GitHub template" = [
      { "Overview" = "template_documentation/onboarding/index.md" },
      { "Template quick start" = "template_documentation/onboarding/quick_start.md" },
      { "Customize and clean up" = "template_documentation/onboarding/customize_repository.md" },
    ] },
    { "User guide" = [
      { "Installation" = "template_documentation/user_guide/installation.md" },
      { "Quick start" = "template_documentation/user_guide/quick_start.md" },
      { "Project structure" = "template_documentation/user_guide/project_structure.md" },
      { "Development tools" = "template_documentation/user_guide/development_tools.md" },
      { "Testing" = "template_documentation/user_guide/testing.md" },
      { "Documentation" = "template_documentation/user_guide/documentation.md" },
      { "CI/CD" = "template_documentation/user_guide/ci_cd.md" },
      { "Packaging" = "template_documentation/user_guide/packaging.md" },
      { "Customization" = "template_documentation/user_guide/customization.md" },
    ] },
    { "Development notes" = [
      { "Code quality" = "template_documentation/development/code_quality.md" },
      { "Changelog" = "template_documentation/development/changelog.md" },
      { "Troubleshooting" = "template_documentation/development/troubleshooting.md" },
    ] },
  ] },
]

Writing Documentation¶

Markdown Basics¶

Use standard Markdown with Zensical extensions:

# Heading 1

## Heading 2

**Bold text** and _italic text_

- Bullet list
- Another item

1. Numbered list
2. Second item

[Link text](url)

```python
# Code block
def function():
    pass
```

!!! note
    Admonition for notes, warnings, etc.

Front Matter¶

Add metadata to pages:

---
title: Page Title
description: Page description for SEO
tags:
    - tag1
    - tag2
---

API documentation¶

mkdocstrings (Python)¶

API pages are written in Markdown under docs/api/ and can embed objects from your package using mkdocstrings, configured in zensical.toml:

[project.plugins.mkdocstrings.handlers.python]
inventories = ["https://docs.python.org/3/objects.inv"]
paths = ["src"]

[project.plugins.mkdocstrings.handlers.python.options]
docstring_style = "google"
inherited_members = true
show_source = false

Writing Docstrings¶

Use Google-style docstrings:

def function_name(param1: str, param2: int = 0) -> str:
    """Brief description of what the function does.

    More detailed description explaining the function's purpose,
    behavior, and any important notes.

    Args:
        param1: Description of param1.
        param2: Description of param2. Defaults to 0.

    Returns:
        Description of return value.

    Raises:
        ValueError: When something goes wrong.

    Examples:
        >>> function_name("hello", 1)
        'hello1'
    """
    return f"{param1}{param2}"

Class Documentation¶

class MyClass:
    """Brief description of the class.

    Longer description explaining the class purpose
    and how to use it.

    Attributes:
        attribute1: Description of attribute1.
        attribute2: Description of attribute2.
    """

    def __init__(self, param: str):
        """Initialize the class.

        Args:
            param: Description of initialization parameter.
        """
        self.attribute1 = param
        self.attribute2 = None

Building and Serving¶

Local Development¶

# Serve documentation locally
zensical serve

# Open http://localhost:8000

Building for Production¶

# Build static site
zensical build

# Output in site/ directory

Deployment¶

The template includes GitHub Actions for automatic deployment:

GitHub Pages: Automatic deployment on pushes to main

Documentation layout in this repository¶

Home page (`docs/index.md`)¶

Placeholder aimed at end users of your package (API, contributing, security). Replace the title and bullets as your project grows.

Template documentation (`docs/template_documentation/`)¶

Bundled guides that explain this template’s layout and tooling (onboarding, user guide, changelog tooling, troubleshooting). Remove this directory and its nav section when you no longer need them.

API reference (`docs/api/`)¶

Hand-written or generated API pages (see gen_ref_pages.py if you use it).

Standard pages¶

docs/contributing.md — includes the root CONTRIBUTING.md
docs/security.md — security policy

Assets¶

docs/style/, docs/javascripts/ — extra CSS/JS for Zensical

Best Practices¶

Content Organization¶

Progressive disclosure: Start simple, get complex
Cross-references: Link related pages
Consistent structure: Use similar layouts

Writing Style¶

Clear and concise: Avoid jargon
Active voice: "Install the package" vs "The package can be installed"
Examples: Include code examples
Screenshots: For UI components

SEO and Accessibility¶

Descriptive titles: For search engines
Alt text: For images
Semantic HTML: Proper headings hierarchy

Advanced topics¶

Zensical is configured in TOML rather than a mkdocs.yml file. Optional theme tweaks (for example variant = "classic" under [project.theme]) and extra Markdown extensions are already demonstrated in zensical.toml. For a full list of features and plugins supported by your Zensical version, see the Zensical documentation.

Customization¶

Changing Theme¶

Switch to other themes:

[project.theme]
# Default Zensical theme
variant = "material"

Adding Pages¶

Create .md file in appropriate directory
Add to zensical.toml nav
Link from other pages

Custom CSS and JavaScript¶

Paths are relative to the docs directory. In zensical.toml, uncomment and edit extra_css / extra_javascript under [project] (see the comments in that file), or add assets under docs/ and reference them there.

CI/CD Integration¶

Documentation is built in CI when you push to main (see .github/workflows/documentation.yml): dependencies are installed with uv sync --extra docs --frozen, then uv run zensical build writes the static site to site/, which GitHub Pages deploys as an artifact.

Setting Up GitHub Pages¶

To deploy your documentation to GitHub Pages, follow these steps:

1. Enable GitHub Pages¶

Go to your repository on GitHub
Navigate to Settings → Pages
Under "Build and deployment":
- Source: Select "GitHub Actions"
- This allows the documentation workflow to deploy directly
Click Save

2. Configure Site URL (Optional but Recommended)¶

Update zensical.toml to use your GitHub Pages URL:

[project]
site_url = "https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/"
site_name = "Your Package Name"

This ensures links and assets work correctly on GitHub Pages.

3. Verify Documentation Workflow¶

The documentation is deployed automatically by the GitHub Actions workflow:

Go to Actions tab in your repository
Open the Documentation workflow
Verify it runs successfully on pushes to main branch
Check the workflow logs if there are issues

4. Access Your Documentation¶

After the first successful deployment:

Go back to Settings → Pages
You'll see a message like "Your site is live at: https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/"
Click the link to view your published documentation
Bookmark this URL for future reference

5. Custom Domain (Optional)¶

If you want to use a custom domain:

In Settings → Pages, enter your custom domain in "Custom domain"
Update DNS settings with your domain registrar
GitHub will automatically provision an SSL certificate

Troubleshooting Documentation Deployment¶

Documentation Not Updating¶

Problem: You pushed changes but the docs still show old content.

Solution:

Verify the documentation workflow succeeded:
- Check Actions tab
- Open the Documentation workflow
- Re-run if it failed
Clear browser cache (hard refresh: Ctrl+Shift+R or Cmd+Shift+R)
Wait 1-2 minutes for GitHub Pages to rebuild
Verify changes were committed and pushed to main branch

Workflow Fails with Build Error¶

Problem: Documentation workflow fails with "Zensical build failed".

Solution:

Check markdown file syntax
Verify all navigation links in zensical.toml point to existing files
Run locally to debug:
```
zensical build --strict
```
Fix any errors and push again

404 - Site Not Found¶

Problem: GitHub Pages shows 404 error.

Solution:

Verify GitHub Pages is enabled in Settings → Pages
Check the deployment source is set correctly
Wait a few minutes after enabling GitHub Pages
Try accessing from an incognito/private browser window

Troubleshooting¶

Common Issues¶

Build fails: Check Markdown syntax and verify all files exist
Links broken: Ensure relative paths are correct and files exist
API docs missing: Verify docstrings are present and properly formatted
Deployment fails: Check Actions tab for workflow errors

Debugging¶

# Strict mode (catches all issues)
zensical build --strict

# Verbose output (more details)
zensical build -v

# Local preview
zensical serve  # Visit http://localhost:8000

For more information, see the Zensical documentation.

Documentation¶

Overview¶

Zensical Configuration¶

Basic Setup (zensical.toml)¶

Navigation Structure¶

Writing Documentation¶

Markdown Basics¶

Front Matter¶

API documentation¶

mkdocstrings (Python)¶

Writing Docstrings¶

Class Documentation¶

Building and Serving¶

Local Development¶

Building for Production¶

Deployment¶

Documentation layout in this repository¶

Home page (docs/index.md)¶

Template documentation (docs/template_documentation/)¶

API reference (docs/api/)¶

Standard pages¶

Assets¶

Best Practices¶

Content Organization¶

Writing Style¶

SEO and Accessibility¶

Advanced topics¶

Customization¶

Changing Theme¶

Adding Pages¶

Custom CSS and JavaScript¶

CI/CD Integration¶

Setting Up GitHub Pages¶

1. Enable GitHub Pages¶

2. Configure Site URL (Optional but Recommended)¶

3. Verify Documentation Workflow¶

4. Access Your Documentation¶

5. Custom Domain (Optional)¶

Troubleshooting Documentation Deployment¶

Documentation Not Updating¶

Workflow Fails with Build Error¶

404 - Site Not Found¶

Troubleshooting¶

Common Issues¶

Debugging¶

Basic Setup (`zensical.toml`)¶

Home page (`docs/index.md`)¶

Template documentation (`docs/template_documentation/`)¶

API reference (`docs/api/`)¶