Document tables/database structure

[jtniehof]

This PR documents the database tables and overall structure, plus some general cleanup.

• New tables doc that contains a description of every table and every column in that table. This required writing a small Sphinx extension to support documenting SQL, which is included.
• Add a new graphviz-based diagram of the relationships between tables. This replaces the old one which was a static PDF and now out-of-date. The old one was removed.
• A few minor cleanups
  • Replaced a few static HTML links to Sphinx with Intersphinx links, which means we'll link the latest docs and won't be caught out if Sphinx restructures their website a bit.
  • Fixed a little bit of doc formatting that I found along the way
  • Removed the Sphinx imgmath and inheritance_diagram extensions, as we don't use them. I left coverage and extlinks because, although we don't use them, maybe we should!

Attached is the Sphinx output just to make this easier to review: dbp_test.zip. The relevant information is in developer/tables.html

PR Checklist

• [X] Pull request has descriptive title
• [X] Pull request gives overview of changes
• [X] New code has inline comments where necessary
• [X] Any new modules, functions or classes have docstrings consistent with dbprocessing style
• [X] (N/A) Major new functionality has appropriate Sphinx documentation
• [X] (N/A) Added an entry to release notes if fixing a major bug or providing a major new feature
• [X] (see below) New features and bug fixes should have unit tests
• [X] (N/A) Relevant issues are linked in the description (use Closes # if this PR closes the issue, or some other reference, such as See # if it is related in some other way)

I chose not to implement a full unit test setup for the Sphinx SQL extension. I can see maybe spinning that off in the future if it proves useful and extensions look good, but there's no point right now.

[jtniehof]

@balarsen, asking you largely for a sanity check on the tables, but also because I would really like to hear anything you can remember on #103, #104, #105, #106.

@MylesJohnson, if you're bored and remember anything, would be great to hear from you, too :)

[balarsen]

@jtniehof sorry for being a bit out of the loop, can you provide/point me at how to build the docs on the structure? I poked and found table_docs.py table_graph.py but I am out of the loop enough not sure how to run the docs to include the structure. I built the docs but the structure isn't there.

[jtniehof]

@jtniehof sorry for being a bit out of the loop, can you provide/point me at how to build the docs on the structure? I poked and found table_docs.py table_graph.py but I am out of the loop enough not sure how to run the docs to include the structure. I built the docs but the structure isn't there.

@balarsen : if you just "make html" in the sphinx directory, that should do it; the diagram is at the top of the tables.html. This does need graphviz (and Sphinx should complain mightily if you don't have it.) You can also just download the zip of the pre-built docs. table_docs.py and table_graph.py are only needed for making the inputs to the Sphinx; their outputs are checked in.

[balarsen]

@jtniehof weird, I don't see in either what I made of the attached any images. Maybe just totally clueless.

Is this the right place?

I did file the yellow one in the images folder, is that the right one?

[balarsen]

I was able to navigate in the directory structure and find the page, but it wasn't linked to

[balarsen]

Sorry for the 1000000000000000 comments. too many places named "tables"

"Developer Information" -> "Tables"

[jtniehof]

I was able to navigate in the directory structure and find the page, but it wasn't linked to

Top-level index.html, click "developer information", click "tables", diagram is right under the summary table of tables at the top.

[balarsen]

All very good, thank you for updating all this!!