5

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

Kedare
  • 1,289
  • 16
  • 31
  • 3
    I don't know Yard. Could you explain what Yard does, and specifically what features you would expect from a Python equivalent? – Sven Marnach Apr 25 '12 at 20:13
  • Yard is a documentation server, it automatically generate gems (equivalent of eggs) documentation when you install them and can also be used as a standalone documentation generator (like sphinx), it provides a really nice and modern web interface with search, syntax coloration and trees of classes/modules, you can see an example of online documentation here: http://rubydoc.info/docs/yard/frames/file/docs/WhatsNew.md – Kedare Apr 25 '12 at 20:15
  • The features that I am looking for is a documentation server that is more convenient to use than pydoc -p, that would allows me to search in the documentation and to have easy way of navigations into the documentation (like Yard trees) – Kedare Apr 25 '12 at 20:18
  • After generating the documentation with Sphinx, you can also serve it with any web server. And it also has "a really nice and modern web interface with search, syntax coloration and trees of classes/modules". What's missing? Why is "server mode" such a major feature? – Sven Marnach Apr 25 '12 at 20:18
  • Is not a major feature but a plus of having the documentation available instantaneously after having installed the gem without having to generate it manually – Kedare Apr 25 '12 at 20:19
  • Sphinx looks hard to use to simply generate a gem documentation... – Kedare Apr 25 '12 at 20:43

2 Answers2

3

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.)

Sven Marnach
  • 574,206
  • 118
  • 941
  • 841
  • I tried this on a random project (SQLAlchemy) and I only get a module list without any documentation, is this normal ? – Kedare Apr 25 '12 at 21:01
  • @Kedare: I also tried it on a random package (`logging` from the standard library), and it worked for me. The package should be installed in a way that it can be imported by Python, and you should point Sphinx to the directory where the package can be imported from. Sphinx can only automatically build documentation for modules it can import. – Sven Marnach Apr 25 '12 at 21:03
  • Okay, it was a case problem, I did it again with the good cases on package name and it worked :) – Kedare Apr 25 '12 at 21:09
2

Seems kind of unnecessary to implement a web server just to serve up some HTML. I tend to like the *ix philosophy of each tool doing one small thing, well. Not that a web server is small.

But you could look at http://docs.python.org/library/basehttpserver.html

user1277476
  • 2,871
  • 12
  • 10