Source code documentation

[tmillross]

The AB has limited documentation within the codebase. As mentioned by @cmutel in #153, this will make it easier for new contributors. As a new contributor myself, I can attest to the difficulty of writing AB code whilst not understanding the architectural decisions or patterns being used. This is exacerbated by unfamiliarity with PyQT, which has less online support and guidance than expected.

Regarding documentation available online, this website is the only result I've found. It appears to be based on the AB build of 2015, as hosted on BitBucket. So presumably this means that some effort is required to setup a new automated solution which extracts the documentation from this GitHub repo.

The contribution guidelines also don't yet provide guidance on an AB documentation approach.

Questions & lines of action

1. Which documentation conventions should be used in AB? (add to contribution guidelines)
2. Which tech stack should be used for automation? Assuming: Sphinx and ReadTheDocs for hosting, in alignment with BW docs (requires setting up)
3. Any recommendations on how to proceed, or would anybody like to assist with setting up the automation or writing the documentation? (let's get writing! Particularly for new commits)

[bsteubing]

Tom - those are important points - the development of the AB was not very good in terms of documentation. This clearly needs to improve. My recommendation would be to use Sphinx and ReadTheDocs as brightway2 does (@cmutel / @haasad : would you like to add something on this?).

I do think, however, that adding functionality at this moment is more critical than adding documentation to existing code. Instead, I think the way forward is to really document new functionality properly. Of course, it might make sense to add to documentation for parts of the code that are currently not easy to understand and you just took a deeper look at this and can quickly add a docstring.

[cmutel]

+1 to Sphinx and ReadTheDocs. One key technique I now use a lot is to mock out most dependencies in conf.py when building the documentation - this makes the docs build much faster. See wurst for an example.

I don't know who owns the current RTFD site, but it is quite easy to set up automatic doc building. Easier to just do it than discuss it :)