nerdvegas
commented
10 years ago I don't mind if the doc type is doxygen or sphinx - what I care about is compact comments. For that reason, I really dislike the numpy style. My preference is for google-style, sans empty lines even better.
A
On Wed, Mar 5, 2014 at 10:07 AM, Chad Dombrova notifications@github.comwrote:
There are a couple of different docstring formats being used in rez right now, we should decide on a convention and stick to it.
First, we need to decide what documentation generator we will use as that will dictate the available styles. I think that sphinx is the obvious choice, because it is the only actively maintained documentation generator for python out there. I've used epydoc, and it was easy to use, but it was already pretty outdated 5 years ago, so I would not bet on that horse now. Doxygen was designed for C++ and its python support is just a hack on top of that. IIRC, it could not do python introspection on live python objects like sphinx and epydoc, it could just parse python code.
So, if sphinx is the choice we have 3 styles to choose from: native, numpy, and google. here's a sphinx extension that adds supports for the latter 2: http://sphinx-doc.org/latest/ext/napoleon.html
Here they are for your simple viewing pleasure:
sphinx
def func(arg1, arg2): """Summary line. Extended description of function. :param arg1: Description of arg1 :type arg1: int :param arg2: Description of arg2 :type arg2: str :returns: Description of return value :rtype: bool """ return True
numpy
def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value """ return True
def func(arg1, arg2): """Summary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value """ return True
A note on sphinx:
If you have not used sphinx before, but you have used other documentation generators like epydoc, it might be confusing at first. It is important to know that sphinx is designed in layers: the primary layer is a pure restructuredText parser, which translates an rst file into rich output like html, usually one html file per rst file. Hence, most of the sphinx documentation covers writing restructuredText documents from scratch and has nothing to say about generating API documentation from source code. That is handled by a set of extensions (namely, the autodoc extension) which generate rst documents from python modules and their docstrings, which are then converted into rich output as a second pass.
Reply to this email directly or view it on GitHubhttps://github.com/nerdvegas/rez/issues/51 .
chadrik
mstreatfield
bfloch
maxnbk
JeanChristopheMorinPerso
There are a couple of different docstring formats being used in rez right now, we should decide on a convention and stick to it.
First, we need to decide what documentation generator we will use as that will dictate the available styles. I think that sphinx is the obvious choice, because it is the only actively maintained documentation generator for python out there. I've used epydoc, and it was easy to use, but it was already pretty outdated 5 years ago, so I would not bet on that horse now. Doxygen was designed for C++ and its python support is just a hack on top of that. IIRC, it could not do python introspection on live python objects like sphinx and epydoc, it could just parse python code.
So, if sphinx is the choice we have 3 styles to choose from: native, numpy, and google. here's a sphinx extension that adds supports for the latter 2: http://sphinx-doc.org/latest/ext/napoleon.html
Here they are for your simple viewing pleasure:
sphinx
numpy
google
A note on sphinx:
If you have not used sphinx before, but you have used other documentation generators like epydoc, it might be confusing at first. It is important to know that sphinx is designed in layers: the primary layer is a pure restructuredText parser, which translates an rst file into rich output like html, usually one html file per rst file. Hence, most of the sphinx documentation covers writing restructuredText documents from scratch and has nothing to say about generating API documentation from source code. That is handled by a set of extensions (namely, the autodoc extension) which generate rst documents from python modules and their docstrings, which are then converted into rich output as a second pass.