Salt: Question: What is the tool chain for Salt's wonderful documentation?

[byteknacker]

I am using the documentation of Salt on a daily basis and it is remarkably well written. In my company, we wish to also produce a documentation that is of such a great quality. But we don't know how.

Would you perhaps mind telling me what tools you use and what the steps are to produce a good documentation that people will read. How do you keep the documentation in sync with the source code?

Many thanks in advance!

[cachedout]

First, thanks for the kind words. We really appreciate it!

The documentation is all produced using the excellent docs tool, Sphinx: http://www.sphinx-doc.org/en/stable/

Since Sphinx can look at Python doc strings and produce nicely formatted docs directly from what's in the code, for the most part we only have to maintain what's in the function docstrings and Sphinx takes care of formatting all of that into nice, pretty online docs.

The Sphinx configuration can get a little complex. For reference, you can see ours here: https://github.com/saltstack/salt/blob/develop/doc/conf.py

We also rely on Pylint to ensure that all contributions contain at least some documentation for each new user-facing function that's added.

Beyond that, we most often rely on our excellent community to keep docs flowing in. They have written much of the tutorial section and expanded it greatly in cases where we wrote the initial articles.

I hope that helps. I'm happy to answer any follow-up questions. Thanks!

[byteknacker]

Thank you for the rapid reply. We are already looking into using Sphinx now based on what you said. Are you also using any kind of plugins for Sphinx? Also what kind of comment language are you using? Is it markdown or something else?

Would it be possible to use many different kind of syntax for the comments from which sphinx generates the documentation?

[cachedout]

@byteknacker You've pretty much exhausted my Sphinx knowledge. ;]

I will refer you to @jacobhammons and @whiteinge . They won't be online for a few hours but hopefully they should see this in the morning and reply with additional info. Thanks!

[byteknacker]

@cachedout no worries at all, I am really glad that the help is coming so quickly.

[jacobhammons]

what kind of comment language are you using? Is it markdown or something else?

Would it be possible to use many different kind of syntax for the comments from which sphinx generates the documentation?

Sphinx uses reStructuredText markup syntax. There has been interest for a long time in getting markdown support in Sphinx, you can search the sphinx issues database on github to see how this is progressing.

For a new project I'd recommend using Google style or NumPy style docstrings. These are supported by https://pypi.python.org/pypi/sphinxcontrib-napoleon/ which is now built-in to Sphinx. You just need to add it to your extensions list. Otherwise you can use the built-in Sphinx syntax. I would pick one format and stick with it, it will make your code much easier to read and maintain.

Are you also using any kind of plugins for Sphinx?

• sphinx.ext.autodoc: plugin that does the automatic Python doc work.
• sphinx.ext.extlinks: Setting up extlinks to common URLs will save you time and make your docs easier to read. Example at https://github.com/saltstack/salt/blob/develop/doc/conf.py#L301
• sphinx.ext.intersphinx: easily link to core Python docs.
• sphinx.ext.autosummary: generates pages like this https://docs.saltstack.com/en/latest/ref/modules/all/index.html

Not a plugin, but in Salt we recommend using :ref: instead of :doc: to link around your docs, http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations since it doesn't rely on the file path.

Our custom extensions are in https://github.com/saltstack/salt/tree/develop/doc/_ext, not sure that any of these would be useful outside of Salt though.

Thanks!

[byteknacker]

@jacobhammons thanks a lot for your very useful advice. I just noted them all down and we are actually going to implement some of your suggestions. Have a nice day!

[Ch3LL]

@byteknacker you okay with closing this since it seems all your questions have been answered?

[byteknacker]

Yes absolutely. Thanks a lot!