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. #281
• [x] 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 #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.

[ghost]

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