API-doc has run-on sentences

[purva-thakre]

As we rely on google-style docstrings, there is no convention to allow lists in the description of the different sections of a docstring. Portions of our API-doc have run-on sentences because someone used a list in the section description which appears as badly formatted sentences publicly.

Intended	in API-doc

[purva-thakre]

@natestemen Is this what you were referring to?

[natestemen]

Not really. I was thinking we could take inspiration from how numpy documents kwargs objects, but I haven't been able to find what I was looking for. One thing I did find, however, was that for numpy.clip they redirect to a different page for info on what kwargs can look like. Not necessarily suggesting we do that, just worth noting.

[cosenal]

See #2472 for a related issue and potentially a solution that could fix both. 🐦‍⬛🐦‍⬛ 🥌

[Kuzay3t]

I want to help, how can i assist?

[natestemen]

The goal here is to go through the docstrings and ensure kwargs variables are formatted properly. You can find an example where this is not the case in the issue description.

[Shivansh20128]

Hi @cosenal @purva-thakre ! I tried adding linespaces between the sentences in the list in kwargs, and the problems seems to b resolved now (though some more reformating needs to be done). I have made a draft PR and built the docs which you can find here. If you go below to this section, you can see the kwargs list does not have run-on sentences anymore.
This is how it looks now. Let me know if I should go forward with this and apply this everywhere with a better formatting.

[cosenal]

@Shivansh20128 Thanks for testing this. Interesting that the newlines carry over in the rendered file, e.g., the one betwenn "...select the" and then "non-Clifford...".
Your solution makes sense to me, let's hear from @purva-thakre as well.
We may also want a way to format this automatically.

[purva-thakre]

We may also want a way to format this automatically.

I agree with this.

I do not know which tool would be preferable etc. I will defer to other maintainers of this project for their opinion as I won't be responsible for the long-term upkeep of documentation dependencies.

[Shivansh20128]

So shall I make the changes I mentioned or wait for a method for automatic formatting?

[gluonhiggs]

I think natestemen has already tried to find how numpy handles this issue automatically. I have tried also, but couldn't find anything explicit. Maybe we can write a custom command in Makefile to do it.

[natestemen]

@Shivansh20128 I like what you've started so far! Let's just try to find all the cases like this for now and ensure they are correctly rendered. Since we've looked and there wasn't something that automatically formatted the docstrings easily, lets fix this and focus our efforts elsewhere.