Refactor python docstrings to string literals

[anthony-santana]

We currently use the google style convention for python documentation. Up until this point, however, we've been manually formatting a single string with end-lines. We should refactor all relevant documentation to use string literals, such that the documentation is more readable and easier to maintain/debug. Example from py_kernel_builder

Current docstring

                      "The data-type representing a qubit argument to a "
                      ":class:`Kernel` function.\n"
                      "\n.. code-block:: python\n\n"
                      "  # Example:\n"
                      "  kernel, qubit = cudaq.make_kernel(cudaq.qubit)\n"

Reformatted docstring (semi-pseudocode)

                      """
                      The data-type representing a qubit argument to a 
                      :class:`Kernel` function.

                      .. code-block:: python
                         # Example: 
                         kernel, qubit = cudaq.make_kernel(cudaq.qubit)
                      """

[pranavdurai10]

Hi @anthony-santana, I'd like to work on this issue. Can you assign me for it?

[anthony-santana]

Hi @pranavdurai10, I just assigned it to you. I'd recommend breaking this one up into smaller PR's so it's easier to review. Let me know if you'd like to chat about any other specifics!

[pranavdurai10]

Thanks for assigning this task to me, @anthony-santana.

1. Can you assist me in splitting this issue into smaller PR's?
2. Please mention the files which requires changes.

[anthony-santana]

Yeah absolutely, thanks for working on this!

Everything will be in the python/runtime directory, and specifically the python/runtime/common and python/runtime/cudaq folders. You could probably do the whole common folder in one PR, then I'd break up the PR's for the cudaq folder into one for each sub-folder in there.

We'd like to update the docstrings for each binded class and function to use either string literals or something like R"pbdocfrom pybind11 (see here). The example I posted in the original issue gives you an idea of what it should look like -- using the google style guide -- we've just run into issues in the past with sphinx generation errors.

To build the docs locally, you can run the scripts/build_docs.sh file, which should handle most dependencies for you. It has further instructions that you can look through too.

You shouldn't have to touch this file at all, but this is the endpoint file that our python docs are spun up off of. That file takes the names of the binded classes and other functions and it gets their docstrings from the python bindings via pybind11.

[pranavdurai10]

@anthony-santana, I've just submitted my first PR for this issue. However, the CLA Assistant Lite bot isn't showing me a checkbox to accept the Contributor License Agreement.

[amccaskey]

Just copy that text (I have read the Contributor...) into the comment box and submit. Should work after that.

[bettinaheim]

We will need to pick this back up after cutting the release branch - it seems something is not working well with the change, but I haven't had a chance to look closer at the issue.