What is the relationship between docutils and Sphinx?
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.
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.
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:
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?