Convert wiki to ReST docs in actual QATrack+ repo.

Issue #150 resolved
Randle Taylor created an issue

I'm not totally happy with using the Wiki as the official documentation and I would like to move the documentation from the Wiki to the actual QATrack+ repo. In addition, I would like to move to using Restructured Text instead of markdown as the markup language. From my perspective some of the pros and cons are:

Pro's:

  • ReST is quite a bit more sophisticated than markdown (also a con) and can generate nice table-of-contents etc.
  • Switching to ReST will allow us to use the nice standard Python documentation tool Sphinx
  • Sphinx has multiple output targets including HTML & LaTeX (which can then generate pdfs)
  • Putting the docs directly in the repo will allow us to host our documentation on readthedocs.org which is free, attractive and has lots of nice features (including integration with bitbucket)
  • readthedocs.org allows us to tightly couple the documentation to the QATrack+ version which will become increasingly more important. Not everyone will be on the same version all the time and I'm worried the docs will start to get muddled with respect to versions. You can work around this in a wiki, but I really like being able to tie doc versions to git tags & branches.

Con's:

  • Raises the barrier somewhat for contributing to the documentation.
  • ReST is a bigger and more confusing/arcane markup format than markdown.

Feel free to comment if you have any thoughts :)

Comments (8)

  1. Simon Biggs

    I could give this an initial try? I could make a pull request into the py34 branch... Initially I would just use on the current wiki files...

    pandoc --from=markdown --to=rst --output=README.rst README.md

  2. Simon Biggs

    I have done an initial quick convert of the wiki to ReST: http://www.simonbiggs.net/qatrackdemodocs/

    I used the following method:

    http://nbviewer.jupyter.org/urls/bitbucket.org/SimonGBiggs/qatrackplus/raw/4466007e145472523acbdd419f73a9bf44d9e61b/docs/Converting%20Wiki.ipynb?at=simon_testing_py34&fileviewer=file-view-default

    Some of the files didn't convert and therefore weren't included. However I am sure that can be solved.

    The table of contents isn't yet fixed either. But as a proof of concept to address this issue I think this could be a way forward.

  3. Log in to comment