Documentation of Puppet code using sphinx
Sphinx is the primary documentation tooling for most of my projects. I use it for the Linux command line book too. Last Friday while in a chat with Leif about documenting all of our puppet codebase, I thought of mixing these too.
Now puppet already has a tool to generate documentation from it's code, called puppet strings. We can use that to generate markdown output and then use the same in sphix for the final HTML output.
I am using https://github.com/simp/pupmod-simp-simplib as the example puppet code as it comes with good amount of reference documentation.
Install puppet strings and the dependencies
$ gem install yard puppet-strings
Then cloning puppet codebase.
$ git clone https://github.com/simp/pupmod-simp-simplib
Finally generating the initial markdown output.
$ puppet strings generate --format markdown --out simplib.md
Files 161
Modules 3 (3 undocumented)
Classes 0 (0 undocumented)
Constants 0 (0 undocumented)
Attributes 0 (0 undocumented)
Methods 5 (0 undocumented)
Puppet Tasks 0 (0 undocumented)
Puppet Types 7 (0 undocumented)
Puppet Providers 8 (0 undocumented)
Puppet Plans 0 (0 undocumented)
Puppet Classes 2 (0 undocumented)
Puppet Data Type Aliases 73 (0 undocumented)
Puppet Defined Types 1 (0 undocumented)
Puppet Data Types 0 (0 undocumented)
Puppet Functions 68 (0 undocumented)
98.20% documented
sphinx setup
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install sphinx myst_parser
After that create a standard sphinx project or use your existing one, and update the conf.py with the following.
extensions = ["myst_parser"]
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
Then copy over the generated markdown from the previous step and use sed
command to update the title of the document to something better.
$ sed -i '1 s/^.*$/SIMPLIB Documenation/' simplib.md
Don't forget to add the simplib.md file to your index.rst and then build the HTML documentation.
$ make html
We can still improve the markdown generated by the puppet strings command,
have to figure out simpler ways to do that part.
