Exposing API, examples and documentation

[davidjb]

This is a great library and it works really well.

A suggestion I'd like to make is that having more information visible about what the library does (and indeed how useful it is) would help others both find, understand, and use this library.

There's heaps of useful documentation already within the code & the various examples, so exposing that's straight forward. My suggestion is to use Sphinx for the task -- it can autodocument from the Python code, integrates with http://readthedocs.org for hosting/autoupdating, and more. The only minor note to mention is that Sphinx is built around using reST, rather than Markdown, as I see the README is written in.

If you're interested, I've got some code together that I've been playing around with that I can put into a pull request. Essentially, it would add almost no overhead to the code - just adding an optional 'extras_require' dependency on Sphinx, and perhaps a few minor tidy-ups in the documentation. Happy to do the work, however, to help improve things & make it easier for all to work with.

Thoughts?

[faucamp]

Argh, wrong issue number; please ignore the commit message above.

As for your documentation idea, I completely agree - I've been meaning to get round to actual documentation for a 1.0 release. As for the actual technologies: the docstrings are in epydoc format, and the markdown is there simply because I wanted a nice-looking github front page. ;) To be honest, it's been a while since I've done proper documentation for/from Python code (hence the epydoc docstrings); I'd be happy to use whatever you have to offer.

[davidjb]

No worries. The documentation you've got inside the code has been great -- made it really easy to understand how things were operating - so my thoughts were just a matter of exposing that info, and perhaps adding a bit more.

My suggestion of Sphinx/ReadTheDocs is (probably) best-practice for Python at present -- it's effectively all I see on projects I've committed to. Eg Sphinx to generate the docs, and RTD to run the processing and serve the documentation to the web in HTML/PDF/etc formats. I'm not overly familiar with Epydoc, but it looks as though that project hasn't been updated in a while, and I think I remember reading something about incompatibility between later versions of Docutils. But that said, since much of the syntax for docstrings matches what Sphinx's "autodoc" module uses, and the quick Sphinx conversion I did in my local copy of the package worked pretty well without almost any work on my part, seemingly living up to its namesake :)

I'll clean this up and pop it into a pull request later today if I get a chance.

[davidjb]

I've just been learning more about Epydoc. The markup between that and Sphinx's autodoc is almost the same -- just need a change of '@' prefixes into ':' characters: http://sphinx-doc.org/markup/desc.html. So the change over was straight forward.

Apparently Epydoc has issues with Python 2.7+, which is interesting. Python itself apparently uses Sphinx, so that's probably the best move: http://wiki.python.org/moin/DocumentationTools

[davidjb]

Also, I was thinking about the Changelog as well -- could this be made part of the main documentation (eg converted into reST as well)? If so, let me know and I'll put some code together.

[faucamp]

The ChangeLog (and AUTHORS) is basically throwback from my Fedora contributor days, and is meant more for package-level docs - helping a distribution packager (rpm/deb etc) indicate what changed during major versions (I always appreciated it when an upstream project did this). Right now I don't think it's necessary to include it in the main docs as the value to an end-user is not that great, and I prefer the package-style format for it - but hey, if you think it's useful, go ahead. :)

[davidjb]

Totally agree -- a similar style of Changelog is fine, it would just be some formatting changes to bring it into line with the rest of the documentation. From an integrator and developer's perspective, having the change log exposed is extremely useful, because it shows you exactly what's happened (just as you've mentioned) within the project. From an integrator's perspective, then it's straightforward to tell what changes might affect existing code. Going looking for the change log is possible, but since it can easily be included, that's my thinking.

My one suggestion would be that this becomes even more useful if the change log is updated together with each change during development. So, if a new commit takes place for a fix or for a new feature, adding an entry into the change log in that same commit makes it easy to see what happened when (and with what exact code). Upon releasing a new version, the change log is already fully up-to-date.

I'll tweak the changelog and send a pull request for you to eyeball. Cheers!