WIP: Read the docs

[ross-spencer]

This commit is starting to create a framework for creating the necessary documentation for both developers, and users. I wanted to explore what we can do with standard tooling which we use in other projects, and share some of that learning with the team, although they may already have this know-how so it might just be for myself.

Connected to #33 which might be developed out of this effort, but it might be better suited under a documentation effort.

To preview:

• Clone this repo.
• Open the docs/_build/html directory in your favorite flavor of web-browser.
• A non-css preview here <-- it doesn't look so great!

To use:

• Install requirements via pip install -r requirements/dev.txt
• Use the Makefile in the docs folder, e.g. make html once changes have been made to code.

How I created this documentation so far:

1. Made a docs directory.
2. Then ran sphinx-quickstart to generate a layout. Default values were selected
   unless other values were needed.
3. Then modified a few more values based on this sheet; https://medium.com/better-programming/auto-documenting-a-python-project-using-sphinx-8878f9ddc6e9
   and projects like a3m and mets-reader-writer for which we already have some
   documentation.
4. Then we can run sphinx-apidoc. This generates our documentation!
   sphinx-apidoc -o ../docs ../AIPscan
5. I needed to add 'modules' as a line to index.rst.
6. Can then customize the index.rst which is only updated once. Unless it is
   recreated (source control). And we can add links to other modules and also
   annotate some of the bits and pieces that we want to drape people's
   attention to.
7. Can add other custom rst files, for example, I added overview.rst.
8. Changes to the documentation in the code can be added to the docs via
   make html.

TODO:

• We can add a task to CI to test for good doc formatting in code.
• Decide what the minimal level of information is we want for AIPscan via these docs.
• Look for formatting linting tools, e.g. Google style, and decide what we'd like.
• Add to readthedocs.
• Anything else?

Where this takes us...

Python doesn't seem to be as well suited to this as other languages, i.e. it's not as integrated, and pydoc can be a tad flaky, but one nice impact of documentation from code, like this, and why it is connected to #33 is that we can improve the quality and consistency of our docstrings by inspecting them through the docs.

For example:

An example of a simple module summary using a module docstring:

An example of nice function level documentation from Tessa:

A much more basic one from myself, which might not be the style we adopt moving forward:

We can become more fluent with how we format our docstrings which we use to decorate our code. One small example based on Tessa's approach might be to then add pre-formatted text for code within strings, e.g. for the dict reference, and how the dict is used, e.g. somedict[somevalue].