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