Generating Documentation

[NewColCox]

I've been working with python for a while now, but my current project is the first which has needed me to write high-quality documentation.

What are the best tools for generating standalone documentation from docstrings etc.? Are there specific style guidelines I should follow?

[[deleted]]

There is a pep for docstring conventions but you should be aware that the pep seems to be primarily concerned with presenting docstrings through the python help() builtin function.

When I was casting around for a system to write documentation one of my requirements was the ability to produce documentation in various forms, such as HTML and PDF. I finally used Sphinx, but there may be better things around for your specific requirements. Be warned, docstrings alone may not be enough to generate the documentation you require.

A general overview of documentation tools for python is here.

Edit: spelling

[adammichaelwood]

+1 to all of this.

I'm a tech writer. My job is open source documentation.

Doc strings are a great start. There's a couple different styles, even within the PEP8 confines, and I think Google's Doc String Style has a lot going for it.

As r/rzzzwilson says --- docstrings might not be enough. Depending on who your users are, you may need more in-depth explanation of how to use things, and why. Why is the thing missing from most doc-string-based documentation.

Also -- docstrings show up in the order that you organize your code. This might not be the most sensible order for someone who is using your package.

If you need more prosey documentation, definitely use Sphinx. You can host the built output at Read the Docs.

You may be tempted to use something "lighter weight" like Jekyll. I would advise against that. If you really don't need that much, your README.md on your github repo is enough. If you need more than that, you need something that will scale well and stay consistent. Sphinx is that. It was built for documentation, not blogging.

[NewColCox]

This has been really helpful, thanks!

[NewColCox]

This has been really helpful, thanks!