I spent a little bit of time and put together a really small demo of what our documentation could look like using Sphinx (http://sphinx.pocoo.org/). I stress that this is a _demo_ and I didn't spend much time on it - the content is pretty sparse and not very good. If we're interested in looking into this more, I can spend more time on it.
For the demo, I converted the AutoQA wiki page verbatim (other than the added section for module docs) and generated doc for bodhi_utils. I listed some of what I think the advantages and disadvantages of switching to Sphinx would be.
Code: - https://github.com/tflink/autoqa-devel * To generate the HTML docs, go to the doc/ dir and type 'make html'
Demo: - http://tflink.fedorapeople.org/autoqa/sphinxdemo/
======================================== Advantages: ======================================== - Keep documentation in mostly one place * Obviously some stuff should stay in trac (planning) and other stuff in MW (tie-ins with Fedora)
- Allow for documentation changes between releases without messy namespace issues. * Instead of worrying when wiki pages will go live with not-yet-true information, keep the info in master and it only shows up as the current official documentation once we release * This hasn't been much of an issue for us yet, but it will be once we do our first major overhaul of AutoQA and break some backwards compatibility
- Integration of generated API docs and written docs
- Easier generation of an autoqa-docs package once we start packaging
- More encouragement to clean up docstrings * I know that I've not been as good about good docstrings as I could be - having them more visible in API docs might help improve their quality :)
======================================== Disadvantages: ======================================== - It's different * reStructuredText is nice but it's not mediawiki or moin * links and global substitutions are a little more difficult * requires compilation instead of hitting the preview button * Harder for people who aren't already AutoQA devs to contribute docs
- Requires conversion * The conversion process for syntax is pretty straight-forward but it would take time.
- Lends to a different documentation style * I think that Sphinx works best with more of a book-like style than we've been doing thus far (more atomic pages). Converting what we have to start would be fine but we might want to look into documentation refactoring. * pytest is a good example of what this could look like - http://pytest.org/latest/
Thoughts?
Tim