Search code examples
pythonrubydocumentation-generationyard

Is there an equivalent of Ruby's Yard in Python?

I use both Python and Ruby and I really love the Ruby's Yard documentation server :

http://yardoc.org/ ,

I would like to know if there is an equivalent in the Python world ? The "pydoc -p" is really old, ugly and not comfortable to use at all, and it don't looks like Sphinx and Epydoc support the server mode.

Do you know any equivalent ?

Thank you

Solution

  • Python packages don't really have a convention where to put the documentation. The main documentation of a package may be built with a range of different tools, sometimes based on the docstrings, sometimes not. What you see with pydoc -p is the package contents and the docstrings only, not the main documentation. If this is all you want, you can also use Sphinx for this purpose. Here's sphinx-server, a shell script I just coded up:

    #!/bin/sh
sphinx-apidoc -F -o "$2" "$1"
cd "$2"
make html
cd _build/html
python -mSimpleHTTPServer 2345

    Call this with the package directory of the package you want to have information on as the first argument and the directory where to build the new documentation as the second argument. Then, point your browser to http://localhost:2345/

    (Note: You probably want to remove the webserver invocation from the script. It's more for the purpose of demonstrattion. This is assuming Python 2.x.)