Ensure valid RST in docstrings

[peterjc]

Description

Work in progress for #1140, fixing RST violations reported by docutils via flake8-rst-docstrings

Checklist

• The above description motivates these changes.
• There is a unit test that covers these changes.
• All new and existing tests pass locally and on Semaphore.
• Parameters have type hints with PEP 484 syntax.
• Functions and classes have useful sphinx-style docstrings.
• (New Feature) The docs have been updated accordingly.
• (Bugfix) The associated issue is referenced above using
  auto-close keywords.
• The changelog is updated,
  including author and PR number (@username, gh-xxx).

[appleby]

This is great, thanks for doing this. I'm not sure what's going on with the semaphore tests, test pass for me locally.

As mentioned in #1140, let's wait on @karalekas to see what he thinks about rending bra/ket notation. Otherwise, this looks great so far.

[peterjc]

Apparently semaphoreci is unhappy, but I don't see any error message - this is my first time interacting with that platform so I may be missing where to click (or perhaps I need to register an account with them)?

[appleby]

I think you need to be a project admin to see the semaphore logs? It looks like the semaphore tests are failing because the quilc server was unresponsive... lot's of timeout errors trying to connect to quilc.

[karalekas]

Reran it, looks like the build is passing now! Thanks for doing this -- I'd agree with @appleby that I think all docstrings should be valid RST. Our API documentation is currently incomplete, which is why some of the docstrings aren't included, but in general I think we should aim for them all to be valid and consistent. 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.

[peterjc]

I think this is all the low hanging fruit, the remaining possible issues:

$ flake8 --select RST --rst-roles ref,py:class,py:func --rst-directives versionadded,deprecated pyquil/
pyquil/gates.py:0:1: RST902 Failed to parse __all__ entry.
pyquil/gate_matrices.py:0:1: RST902 Failed to parse __all__ entry.
pyquil/unitary_tools.py:178:1: RST301 Unexpected indentation.
pyquil/unitary_tools.py:179:1: RST201 Block quote ends without a blank line; unexpected unindent.
pyquil/tests/test_numpy_simulator.py:276:1: RST213 Inline emphasis start-string without end-string.
pyquil/tests/test_numpy_simulator.py:280:1: RST213 Inline emphasis start-string without end-string.
pyquil/experiment/_program.py:52:1: RST214 Inline literal start-string without end-string.
pyquil/experiment/_program.py:52:1: RST214 Inline literal start-string without end-string.

Both RST902 Failed to parse __all__ entry are down to dynamically defined __all__ (might go away if I had pyquil installed), although I believe using tuples (immutable) over lists (mutable) is recommended elsewhere for the __all__ values.

The pyquil/unitary_tools.py indentation had me scratching my head, but I don't have enough experience of this part of RST as used in parameter lists to fix the warning.

Finally the RST213 Inline emphasis start-string without end-string messages from pyquil/tests/test_numpy_simulator.py are a special case, see peterjc/flake8-rst-docstrings#18

[appleby]

Personally, I think it's fine to punt on the above issues that don't have an obvious solution.

If you don't mind, please just add a line to the changelog and I think this is good to go.

[peterjc]

Change log entry added (rebased first to pre-empt the likely merge conflict in the change log).

[appleby]

This is great thanks for contributing.

[karalekas]

Thanks (again) for contributing!! 🙌