Sphinx Integration
A primary motivation for yamldoc
was to generate documentation for YAML configuration files dynamically, in order that documentation does not outpace development. I have plans to include yamldoc
in a Sphinx extension in the future, but for now there is a simple way to generate your parameter references with each build of the documentation.
Sphinx Setup
For this example, we have chosen to place our Sphinx documentation in the docs/
folder. Inside this folder is a directory for the source scripts, a directory for the built HTML files (if building a website), and a Makefile
.
You must first install some sort of Markdown parser so that the markdown that is produced from yamldoc
can be understood by Sphinx. For this we recommend recommonmark
. Since there is no support for markdown style tables in this package, you have to also install sphinx-markdown-tables
.
Install these two packages with pip
.
pip install recommonmark sphinx-markdown-tables
Sphinx Configuration
You must include these two new extensions in your sphinx documentation. Open the source/conf.py
configuration file that Sphinx uses to load extensions, and add both of these to the list called extensions
.
extensions = [
...
'recommonmark',
'sphinx_markdown_tables'
]
Manual Method
If you don't mind running yamldoc
every time you change a YAML file, you can run it manually.
Since yamldoc
prints to STDOUT by default, just create the documentation and pipe it to a convenient file:
yamldoc your/yaml/file.yaml > docs/source/parameters.md
Be sure to include this in the table of contents (TOC) of your project (typically docs/source/index.rst
)!
Automatic Method
If you've made it this far, you're probably in search of a "set it and forget it" method. I will be the first to admit that this is a bit hack-y, but it hasn't broken for me yet. Until I make a real Sphinx extension, edit the docs/Makefile
in your favourite text editor. The last line should look something like this:
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Simply add a file to generate your parameters.md
file with yamldoc
before any building is done with Sphinx.
%: Makefile
yamldoc your/yaml/file.yaml > source/parameters.md`
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Remember to include this new file in the table of contents (TOC) for your project (typically docs/source/index.rst
)!
For more details on how to document YAML files with yamldoc
, see the tutorials.