What is the relationship between docutils and Sphinx?

Question

There seems to be a plethora of documentation tools for Python. Another one that I\'ve run across is epydoc. It seems like Sphinx is the de facto standard, because it\'s used to

Answer 1

It seems like Epydoc is, if not dead, at least pining for the fjords.

Sphynx with the sphinx-apidoc command and the autodoc extension looks to be the most popular option for API docs at this time.

Good examples are:

• requests (src)
• boto (src)

See: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)

Sphinx encourages a more narrative style than tools in the javadoc mold, but maybe this is a good thing?

Answer 2

epydoc and Sphinx are different types of tools.

They are the same in that they:

• Both use ReST via docutils.
• Both are very Pythonic in their focus
• Both can generate HTML and PDF documentation

They are different in their focus.

• Epydoc is focused on API (Developer) documentation. You get more results quicker with Epydoc. You point it at your source code and you get something. This is what I want from an API documentation tool.
• Sphinx is focused on general (User) documentation. While Sphinx does pull a lot of information from your source code you need to put a little more into it. Sphinx can generate API documentation but, it's not as straight forward, and IMO doesn't do as good of a job as Epydoc. I know some will disagree because Sphinx is chosen for Python. BUT, it depends on how much work you want to put into it. I do love Sphinx for general documentation.

So it depends on how much work you want to put into it and what you are documenting.

Answer 3

I recently changed from Python2 to Python3 and found that there was no Epydoc package for Python3. So it seems with Python3 there is a clear focus on using Sphinx as API documentation.