A MkDocs Ledger theme based on Material for MkDocs.
Just follow the following steps.
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]
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
.
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_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
summary: true
- gen-files:
scripts:
- scripts/gendocs.py
- literate-nav:
nav_file: SUMMARY.md
And in scripts/gendocs.py
:
from pathlib import Path
from mkdocs_ledger.docstrings import generate_docstrings
ROOT = Path(__file__).parent.parent
# Path to root package
generate_docstrings(ROOT / "mkdocs_ledger")
To enable support for GitHub Alerts, you need to enable the GitHub Callouts extension.
markdown_extensions:
- github-callouts
Documentation is available at https://ledgerhq.github.io/mkdocs-ledger/
Read the dedicated contributing guidelines.