Ledger theme for MkDocs

This site is both a documentation and a showcase for this theme.

Getting started

Just follow the following steps.

Installation

Just install mkdocs-ledger from the GemFury repository (this requires credentials). Properly chose the extra depending on what you want to document:

# Basic installation
pip install mkdocs-ledger
# Installation with docstring support
pip install mkdocs-ledger[docstrings]
# Installation with `click` documentation support
pip install mkdocs-ledger[click]
# Installation with all features
pip install mkdocs-ledger[docstrings,click]

Configure mkdocs

Just use the ledger theme in your mkdocs.yml configuration:

theme: ledger

For docstrings support, use the mkdocstrings plugin. For click support, use the mkdocs-click plugin.

theme: ledger

markdown_extensions:
  - mkdocs-click

plugins:
  - material/search
  - mkdocstrings

Note

If you override plugins, you need to put every provided plugins, including material/search.

Detailed mkdocstrings configuration

In order to have a shiny docstring reference, you may use the following configuration:

  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          import:
            # Add used libs for external cross-references
            - https://docs.python.org/3/objects.inv
          paths: [src]
          options:
            docstring_options:
              ignore_init_summary: true
            docstring_section_style: list
            filters: ["!^_"]
            heading_level: 1
            inherited_members: true
            merge_init_into_class: true
            parameter_headings: true
            separate_signature: true
            show_docstring_modules: true
            show_if_no_docstring: true
            show_root_heading: true
            show_root_full_path: true
            show_signature_annotations: true
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            signature_crossrefs: true
  - gen-files:
      scripts:
      - scripts/doc.py
  - literate-nav:
      nav_file: SUMMARY.md

And in scripts/doc.py:

from ledger.mkdocs.docstrings import generate_source_documentation

generate_source_documentation("reference", "src/package")

Github Alerts

To enable support for GitHub Alerts, you need to enable the GitHub Callouts extension.

markdown_extensions:
  - github-callouts

References

This theme is based on MkDocs and some extensions so please consult upstream documentations:

• MkDocs: the documentation engine
• Material for MkDocs: the base theme
• mkdocsstrings: docstrings support
• mkdocs-click: automatic documentation for Python Click

Showcase

Demo pages

The following pages are just here to showcase supported features:

• docstrings: showcase docstrings support
• OpenAPI: showcase OpenAPI documentation based on redoc/RedocLy
• Click: showcase click automatic documentation
• Mermaid: showcase mermaid.js diagrams integration

They are using fake or demo data, most of the time took form their feature official website. If you are hacking this theme, don't hesitarte to use those pages to see the result. If you add support for a specific feature, please add a page showcasing it.

Light/Dark mode

This theme comes with support for both light and dark mode so don't forget to try both.

The toggle button (/) is in the top header on the right.