Documentation

[jherrlin]

We need more documentation for the application architecture, run instructions and so on. I have made some tryouts with Read The Docs and it looks good i think. RTD is also very recognized in the python community.

[jherrlin]

@rasjostrom , You have some experience with RTD right? Can I assign you the issue?

[rasjostrom]

Sure I can take care of that. What exactly is it that we need documentation for right now? API and container rules?

I can't be very active at the moment though since I'm not home, but I'll try to contribute as much as I can!

[jherrlin]

It would be nice to start documenting as much as possible, do you think that Doxygen could work out for documenting the code?

Then web APIs and other stuff in RTD?

[rasjostrom]

I think we should use Sphinx throughout. It's super simple, the most common (I think) and most importantly it plays very nice with readthedocs. http://docs.python-guide.org/en/latest/writing/documentation/#sphinx

[jherrlin]

Sound good! How do we start out with that?

[rasjostrom]

https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example has a nice, simple sphinx example:

def public_fn_with_sphinxy_docstring(name, state=None): """This function does something.

:param name: The name to use.
:type name: str.
:param state: Current state to be in.
:type state: bool.
:returns:  int -- the return code.
:raises: AttributeError, KeyError

"""

http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html#template-py-source-file shows an example of a more detailed doc string.

[rasjostrom]

These docstrings can be used to automatically generate reStructuredText, which we just push to readthedocs without having to worry about it.

[jherrlin]

Thats nice! Would you like to set it up and provide some examples?

[jherrlin]

Started out in PR #50 , but still needs more care.

[jherrlin]

How can we get RTD to not run doctests?