docstring formatting problem

[pavlis]

I just noticed that the docstrings for the new MCXcorStacking module that was just merged have a formatting problem with the results sphynx is generating from the docstrings. I see a lot of the docstring that I created have similar problems. When I read the sphynx documentation and a few posts I found with a google search I can't see why there is a formatting problem. I'm going to be working on the documentation in the next couple weeks anyway so this would be a good time to fix this this problem.

Also, if any of you have any experience with this I found one web page that said vscode has a nice plug in to help create sphynx format docstrings. Any one in the group have experience with that?

[pavlis]

I (@pavlis ) have been looking into this issue a bit and realize we have two fundamental problems we need to address to improve the look and readability of our documentations:

1. There are many formatting errors in our docstrings.
2. The look of our pages is less than ideal. Compare mspass.org and current obspy pages and you will see what I mean.

The fundamental cause of 1 is the inability to preview the formatted output from the variant of rst that sphynx uses to generate api pages from docstrings. It is made worse by the fact that the special docstring directives like :param: and :type: seem to have some special formatting properties linked to sphynx that I do not understand. Writing docstrings in our environment is like writing code in a computing language you are not fluent in writing. That is fundamentally why we have a lot of formatting errors. The solution to this problem is that someone in the group needs to commit to learning the tricks of the sphynx variant of rst and got over all the docstrings in the mspass code base to fix the many formatting errors.

Item 2 is almost certainly a configuration setup for how sphynx is run on the code base. I think this one lands on the lap of @wangyinz to fix as he set this up originally. I am not sure how that is working with the makefile in docs. I think we need to have function pages that have the look of obspy pages like this one:

[pavlis]

PS to previous: Click on the "source" link for that obspy function I provide the link to above and you can see how the obspy authors did some of the fancy features on that page. We may not need all of those, but perhaps we need some kind of internal guidelines document for how to write docstrings for mspass like the obspy people provide here