Which docstring style do we use in Bit? Google or RST/Sphinx or anything else? See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html To get rid of all Sphinx warnings like "unexpected indentation" or "definition list ends without a blank line" when I doc-dev/make html if have to use indentations that make the docstrings hard to read in the code. And the Sphinx warnings are also somehow difficult to interpret or solve sometimes...
Good question I had myself, too. Am 28.09.2022 22:46 schrieb J. A.:
Which docstring style do we use in Bit? Google or RST/Sphinx or anything else? See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
Technically our Sphinx use the napoleon extension. Looking into the doc strings it seems to me that most of them are using the Google style. I'm fine with that. But I have to learn some details, e.g. referencing elements in other modules etc
OK, I have checked the existing code and think that Google-style docstrings were used, see eg. here: https://github.com/bit-team/backintime/blob/87775c9cd78b74862f6192c07e278154... So I will write my docstrings with this style too (which I also think is easier to read in the code directly) until I get a veto... On Thu, 2022-09-29 at 06:57 +0000, c.buhtz@posteo.jp wrote:
Good question I had myself, too.
Am 28.09.2022 22:46 schrieb J. A.:
Which docstring style do we use in Bit? Google or RST/Sphinx or anything else? See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
Technically our Sphinx use the napoleon extension. Looking into the doc strings it seems to me that most of them are using the Google style.
I'm fine with that. But I have to learn some details, e.g. referencing elements in other modules etc _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: python@altfeld-im.de
I have created a HOWTO file for creating and maintaining the Sphinx documenation via PR #1317, see: https://github.com/bit-team/backintime/pull/1317/files#diff-fab9dbbffb438c0e... On Sat, 2022-10-01 at 23:17 +0200, J. A. wrote:
OK, I have checked the existing code and think that Google-style docstrings were used, see eg. here: https://github.com/bit-team/backintime/blob/87775c9cd78b74862f6192c07e278154...
So I will write my docstrings with this style too (which I also think is easier to read in the code directly) until I get a veto...
On Thu, 2022-09-29 at 06:57 +0000, c.buhtz@posteo.jp wrote:
Good question I had myself, too.
Am 28.09.2022 22:46 schrieb J. A.:
Which docstring style do we use in Bit? Google or RST/Sphinx or anything else? See: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
Technically our Sphinx use the napoleon extension. Looking into the doc strings it seems to me that most of them are using the Google style.
I'm fine with that. But I have to learn some details, e.g. referencing elements in other modules etc _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: python@altfeld-im.de
_______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: python@altfeld-im.de
participants (2)
-
c.buhtz@posteo.jp
-
J. A.