search

zopefoundation / zope.configuration

Extensible system for supporting various kinds of configurations
https://zopeconfiguration.readthedocs.io
Other
1 stars 6 forks source link

Restore docs from .rst to docstrings? #40

Closed jamadden closed 5 years ago

jamadden commented 5 years ago

Back in https://github.com/zopefoundation/zope.configuration/commit/941b1c84f2a2477116a70ae19a56d96a59fc630e , among others, during the Python 3 porting process, lots (but not all) of the documentation for modules, classes and functions was removed from docstrings and put into the .rst files. The reason was that the docstrings could only be tested under Python 2.

This makes it difficult to know where to document something, or if something even is documented. It might not have a docstring, but still be explicitly documented in sphinx.

Now that the Sphinx doctests have been ported to run on both python 2 and 3 (#24), can we re-unify all the documentation, back into the docstrings? The .rst files would then just consist of some .. automodule:: or at worst .. autoclass:: statements.

icemac commented 5 years ago

+1 to move the documentation near the code it is documenting.