Documentation style of docstrings

[Amir Mohammadi]

Hi Everyone,

Following the new recommendations for writing documentation inside Python functions (docstrings),

I think it is best that you write the docstrings in numpy format. See:
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html

and
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

to see how they look like.

We (at least Andre and I) have been doing this for a while and new packages follow this format:
See https://gitlab.idiap.ch/bob/bob.kaldi/blob/e3d59dd5910ccf138b12f6e27dd1561c8a40d9bd/bob/kaldi/gmm.py#L19 for an example.

Please try to write the new documentation in Numpy style and change the old ones to this format whenever you edit them.

The reason we chose Numpy over Google is that Numpy style is more suitable for scientific documentation where things tend to get long which is the case for Bob packages.

Thanks,

Amir

[Manuel Günther]

Amir,

the automatically generated documentation of C++ code still follows the old style. Interestingly, it should be straightforward to implement the new style guides.

Anyways, I don't really like the style. For example, what happens when functions have different function signatures, e.g., with different return types. This might not be that critical for pure Python functions, but for functions bound from C++ there is a difference for sure. A good example is the `__init__` constructor of many classes that allow both to read from HDF% as well as to get various sets of parameters...
In the current C++ documentation style, all these cases are handled. I don't know how to port that to the new style, which seems to allow only a single signature.

Manuel

[Amir Mohammadi]

Hi Manuel,

The style is intended for Python not C++ and hence the shortcomings.

We do not need to automatically generate Numpy Style docs for our C++ bindings docs.
Since the Numpy style docs will be automatically converted to Sphinx style docs, I think we should just generate those, like:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

Instead of letting our docs be converted two times and hopefully this format supports multiple signatures?!

Anyways, I was mostly emphasizing on Python docstrings.

Amir

--
-- You received this message because you are subscribed to the Google Groups bob-devel group. To post to this group, send email to bob-...@googlegroups.com. To unsubscribe from this group, send email to bob-devel+...@googlegroups.com. For more options, visit this group at https://groups.google.com/d/forum/bob-devel or directly the project website at http://idiap.github.com/bob/
---
You received this message because you are subscribed to the Google Groups "bob-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bob-devel+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Manuel Günther]

Dear Amir,

We do not need to automatically generate Numpy Style docs for our C++ bindings docs.

This is not, what I meant. What I meant is that the C++ documentation should be similar to the python documentation (docstrings) in Numpy style, so that Sphinx can convert that into the Sphinx style (or however this is done).

Currently, we are generating C++ documentation strings automatically from the bob::extension Documentation classes. These strings will be put into the __doc__ slot of the objects and displayed as the python documentation.

The bob::extension::FunctionDoc Documentation class defines the way, the Python documentation (__doc__) of the bound C++ functions is written.

Particularly, it puts the signature of the function in the top (first line) of the docstring. This might be something that we would want to change, so that it matches the Numpy documenting python functions. 

Also, currently it gives each return value a name, which does conflict with the Numpy docstrings, where only the return type is written.

How to handle multiple signatures and/or return values, however, is still unsolved and unclear.

 

Since the Numpy style docs will be automatically converted to Sphinx style docs, I think we should just generate those, like:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

Instead of letting our docs be converted two times and hopefully this format supports multiple signatures?!

I am against writing Sphinx docs for the C++ code. 

First, we would need to generate two different styles, which might be cumbersome. When Sphinx decides to change their style, we need to re-code that for the C++ classes.

Second, some module documentations contain a wild mixture of C++ and Python functions/documentations of these. Combining two different styles into one documentation could be difficult/impossible.

 

Anyways, I was mostly emphasizing on Python docstrings.

I understand that. However, I think we should not make a differentiation whether functions are implemented in C++ or Python, the documentation style should be identical (except for corner cases described above). 

This was my main incentive to reply in this thread.

Manuel