DOC Improve Contributer guide for writting docstrings #31330
Conversation
Co-authored-by: Stefanie Senger <91849487+StefanieSenger@users.noreply.github.com>
doc/developers/contributing.rst
Outdated
| * The "Notes" section is optional. It is meant to provide information on | ||
| specific behavior of the class/classmethod/method. |
There was a problem hiding this comment.
For my education; are "Notes" sections limited to "class/classmethod/method" ? e.g., could they be added to a attributes section or functions?
There was a problem hiding this comment.
For info, adding a "Notes" section using markdown inside an attribute
Notes
-----
would raise an ERROR: Error in "rubric" directive: no content permitted. during build, but not during numpydoc validation.
`
There was a problem hiding this comment.
Interesting, it makes sense its limited to the above list
There was a problem hiding this comment.
Who raises the error? autodoc, sphinx...?
There was a problem hiding this comment.
Not sure, I think it's sphinx right after reading the sources. Here is the traceback from my local experiment:
writing output...
building [html]: targets for 45 source files that are out of date
updating environment: 0 added, 49 changed, 0 removed
reading sources... [100%] modules/generated/sklearn.model_selection.TunedThresholdClassifierCV
/home/arturo/scikit-learn/sklearn/model_selection/_classification_threshold.py:docstring of sklearn.model_selection._classification_threshold.TunedThresholdClassifierCV:126: ERROR: Error in "rubric" directive:
no content permitted.
.. rubric:: Notes
Only defined if the underlying estimator exposes such an attribute when
fit. [docutils]
looking for now-outdated files... none found
| * The "Notes" section is optional. It is meant to provide information on | ||
| specific behavior of the class/classmethod/method. | ||
|
|
||
| * Add one or two **snippets** of code in "Example" section to show how it can |
There was a problem hiding this comment.
Maybe we should add that the code should be runable as is - i.e. should include all required imports?
Reference Issues/PRs
What does this implement/fix? Explain your changes.
During the Unaite x :probabl. sprint I realized this piece of documentation can be improved to avoid common mistakes.
Any other comments?