This is a documentation generator that makes effortlessly accessible what I like and use often from Sphinx.
Highlights
- write your documentation pages in markdown
- use numpy style docstrings
- use your README.md as the welcome page
- use all the goodness that Sphinx and myst_parser provide
-
$
and$$
math environments - (literature) references
- figures and tables
- definition block
- footnotes
- admonitions
-
Installation
The tool is available as a package on PyPI. You can install it via PIP
pip install yadocgen
Usage
Initialize the project using the init
subcommand in the root directory of your repo and answer the questions
$ cd project-dir
$ yadocgen init
Project name: Test project
Author: Ben
Version: 1.0
Sphinx template [karma_sphinx_theme]:
Welcome page [README.md]:
Source code directory [src]:
Documentation directory [doc]:
Output directory [sphinx]:
Once initialized you can (re-)generate your documentation using the generate
subcommand and then use the Sphinx Makefile to compile it
$ yadocgen generate
$ cd sphinx
$ make html
..then you will find your documentation in sphinx/build
.