Should docstrings all be valid RST?

I’ve seen http://docs.rigetti.com/en/stable/ which includes some of the API strings via https://github.com/rigetti/pyquil/tree/master/docs/source/apidocs and Sphinx.

Initially assuming you used all the docstrings, I used it as a test case for my flake8 plugin which validates docstrings as reStructuredText markup. This reported various violations. I’ve looked at a sample, but didn’t find any affecting docstrings actually appearing in your documentation.

e.g. Multiple usage of the string |000...00> without slash escaping the pipe, which docutils (and therefore I would expect Sphinx) sees as a malformed inline substitution reference, “Inline substitution_reference start-string without end-string”. I used your example to build a new test case for the flake8 plugin https://github.com/peterjc/flake8-rst-docstrings/commit/ee3b66a0a0451e0034b1ac7eb849bc3f344c7834

I’ve concluded there is some selection (possibly manual curation) for which of your docstrings appear in the documentation, so perhaps only those need to be valid RST (and you may be checking this anyway via sphinx in strict mode using SPHINXOPTS = -W?).

[peterjc]

Quoting that:

As for braket notation, I think that the double backticks or inline math suggestions are the way to go. I’d lean toward double backticks in most situations because we don’t need to be rendering math when it is gratuitous, but I’m sure there will be situations where we are writing out equations where using :math: is more appropriate.

I agree, very pragmatic.

[karalekas]

closed in #1141