What is the relationship between docutils and Sphinx?
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 generate the official Python docs. Can someone please sort out the current state of Python's documentation tools for me?
Answer
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.