Pick a docstring style about onnxscript HOT 7 CLOSED

See https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html.

from onnxscript.

We use sphinx for document-generation. We need to pick something that will be compatible with that. Why not reST? I am not familiar with this aspect, @xadupre would know better ... any comments @xadupre ?

from onnxscript.

docconvert seems to change the style to follow numpy, google, epydoc, rest. There should be a sphinx extension to process all of them after they are converted. numpy style is used by scikit-learn and is usually easier to read than rest. Just avoid epydoc, it is using javadoc style.

from onnxscript.

sphinx supports google style docs. PyTorch uses it combined with reST style references with sphinx and it functions nicely. We can probably learn from how they do it.

I think google style is easier to read and write since it is less verbose (no :param xxx:) and with clearer indentation. (reST praram and return sections are all lumped together)

from onnxscript.

Sounds good, thanks!

from onnxscript.

Doc pages can be written with markdown using myst https://myst-parser.readthedocs.io/en/latest/

from onnxscript.

Looks like we have sphinx.ext.napoleon already. So we should be safe.

from onnxscript.