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 generate the official Python docs. Can someone please sort out the current state of Python’s documentation tools for me?
Answers:
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.
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?
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.
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?
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.
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?
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.