I'm about to start a project where I will be the only one doing actual code and two less experienced programmers (scary to think of myself as experienced!) will be watching and making suggestions on the program in general.
Is there a good (free) system that I can use to provide documentation for classes and functions based on the code I've written? It'd likely help them a lot in getting to grips with the structure of the data.
I have used epydoc to generate documentation for Python modules from embedded docstrings. It's pretty easy to use and generates nice looking output in multiple formats.
python.org is now using sphinx for it's documentation.
I personally like the output of sphinx over epydoc. I also feel the restructured text is easier to read in the docstrings than the epydoc markup.
See answers to can-i-document-python-code-with-doxygen-and-does-it-make-sense, especially those mentioning Epydoc and pydoctor.
Sphinx can be useful for generating very verbose and informative docs that go above and beyond what simple API docs give you. However in many cases you'll be better served to use a wiki for these kind of documents. Also consider writing functional tests which demonstrate the usage of your code instead of documenting in words how to use your code.
Epydoc is very good at scanning your docstrings and looking at your code to generate API documents but is not necessarily good at giving much more in-depth information.
There is virtue to having both types of documentation for a project. However if you get in a time crunch it is always more beneficial to have good test coverage and meaningful tests than documentation.
I use Sphinx for my project, not only because it looks good, but also because Sphinx encourages writing documentation for humans to read, not just computers.
I find the JavaDoc-style documentation produced by tools like epydoc quite sad to read. It happens all too often that the programmer is mindlessly "documenting" arguments and return types simply because there would otherwise be a gap in the API docs. So you end up with code line this (which is supposed to look like Java, but it's been a while since I wrote Java, so it might not compile...)
/**
* Set the name.
*
* @param firstName the first name.
* @param lastName the last name.
*/
public void setName(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}
There is a very small amount of information in this so-called "documentation". I much prefer the Sphinx way where you (using the autodoc plugin) simply write
.. autofunction:: set_name
and Sphinx will then add a line to your documentation that says
set_name(first_name,last_name)
and from that every Python programmer should know what is going on.