Doc rendering issues

[mpharrigan]

following #278 there are still some problems with the doc build

• cross referencing only happens if you have a dot in the qualified name. This works for cirq.Stuff and tf.Thing but we haven't put any of those aliases in to qualtran. Update: I have figured out how to trick tensorflow_docs to cross-reference unqualified names that I manually list in the api gen script, but I don't know if we want to do this.
• function signature documents the types. It uses the fully-qualified names of things which are too long. This is pretty much the same issue as the above point. Import conventions and our public API #281
• markdown mode is not enabled inside html constructs like tables, so there are backticks everywhere. The tfdocs guy said one could patch the html templates to include a unicode invisible space before all html tags to keep one out of raw-html mode [docs] use definition list for argument docs #284
• types missing from attrs constructor signature
• module pages try to document attrs.frozen as a function defined in that module (?)
• If you put docstrings under a type alias, they don't get picked up and included.
• type aliases like SoquetT are documented where they are imported --- not where they are declared. This is because the local_definitions_filter does not work on type aliases because you can't actually query a type alias for where it was declared (it's a global variable not a class or a function). Manually fixed for egregious violations using a manual list of where they should come from.
• put links between the narrative notebook docs and their reference page
• make warnings into errors from sphinx.
• Run the doc build as part of the CI
• markdown_counts_sigma doesn't render in the docs
• isort:skip_file shouldn't be shown from __init__.py module docstrings
• API reference landing page is pretty sparse. should have a TOC or just be the qualtran module.
• qualtran module page: submodules may or may not have helpful one-line descriptions
• Manual ordering of modules and stuff in the TOC: first, we need to switch from using a glob-based autotoc to parsing the tensorflowdocs toc.yaml (or inherit from their TocBuilder). Then we can try to stop sorting.

I would like to take this ticket and contribute. Can anyone please assign to me