Associate docstrings with public constants

[Strilanc]

• Add cirq/_doc.py with a document function
• Pass public constants into document when they are initialized
• Fixes the fact that e.g. cirq.OP_TREE was being documented using typing.Union's docstring

[mpharrigan]

So there's a way to do this in sphinx -- sortof.

If you read the documentation (particularly for the autodata directive) it says you can just add a docstring under it

OP_TREE = Union[Operation, OpTree]
"""loo loo loo"""

At first blush this doesn't work. That's because api.rst lists cirq.OP_TREE. After some digging, these data docstrings don't make it through import forwarding (sphinx-doc/sphinx#6495). So if you change the listing to ~cirq.ops.op_tree.OP_TREE it shows the docstring. The ~ means "hide the module qualifiers" so it still shows up in the API table as just OP_TREE; but the title of the page and its toc entry has the fully qualified name (which is bad). One could probably fix this with custom autodoc templates. It gets dicey for the places where we do want some sort of name qualification, like in google.XXX and testing.XXX

I think it's important to clearly understand the limitations of autodoc before we re-implement (parts of) it

[Strilanc]

Where did you find documentation on the tilde modifier?

[mpharrigan]

A very good question. I learned it at some point and was actually trying to find documentation on it to see if there were additional options to control the degree of name qualification but alas I couldn't find anything about ~. Empirically it works though

[Strilanc]

After group discussion (including @mpharrigan ), we decided to go with this document function. At least until sphynx finishes their "some future version" milestone fixing it.