Skip to content

Ensure that functions's docstrings pass numpydoc validation #21350

New issue
New issue
Closed
#22780
Closed
Ensure that functions's docstrings pass numpydoc validation#21350
#22780
Labels
DocumentationMeta-issueGeneral issue associated to an identified list of tasksSprintgood first issueEasy with clear instructions to resolve
@thomasjpfan

Description

@thomasjpfan
thomasjpfan
opened on Oct 16, 2021

Background / Objective

Docstrings in Python are string literals that occur as the first statement in a module, function, class, or method definition.

These are some of the characteristics of a docstring:

  • Triple quotes are used to encompass the docstring text.
  • There is no blank line before or after the docstring.
  • The docstring is a phrase ending in a period.
  • more details

numpydoc is one set of criteria to check for consistent documentation structure.

Validating docstrings in scikit-learn

To ensure consistent documentation structure in scikit-learn, we are using numpydoc validation. Currently, documentation tests are failing for various functions. As a temporary fix, we have suppressed error messages in test_docstrings.py. Many of the functions in scikit-learn need to be updated to comply with numpy docstring validation. In the below issue, we provide step-by-step instructions on how contributors can test and update functions.

Note

For those who are running into "YD01: No Yields section found", it could be the cv parameter. Update An iterable yielding (train, test) splits as arrays of indices to:

        - An iterable that generates (train, test) splits as arrays of indices.

Steps

  1. Make sure you have the development dependencies and documentation dependencies installed.
  2. Pick an function from the list below and leave a comment saying you are going to work on it. This way we can keep track of what everyone is working on.
    2.1 Make sure you've created a separate branch from main before editing files for your new contribution. Refer to our contributing guidelines for more information.
  3. Remove the function from the list at:

    scikit-learn/sklearn/tests/test_docstrings.py

    Line 14 in 670133d

    FUNCTION_DOCSTRING_IGNORE_LIST = [
  4. Let's say you picked sklearn._config.config_context, run numpydoc validation as follows.
pytest sklearn/tests/test_docstrings.py -k sklearn._config.config_context
  1. If you see failing test, please fix them by following the recommendation provided by the failing test.
  2. If you see all the tests past, you do not need to do any additional changes.
  3. Commit your changes.
  4. Open a Pull Request with an opening message Addresses #21350. Note that each item should be submitted in a separate Pull Request.
  5. Include the function name in the title of the pull request. For example: "DOC Ensures that config_context passes numpydoc validation".

Note: once you have issued 3 such PRs, feel free to move on to contributing more complex pull requests that involve more thinking and leave those issue fixes to first time contributors for them to learn the github contribution workflow :)

Functions to Update

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationMeta-issueGeneral issue associated to an identified list of tasksSprintgood first issueEasy with clear instructions to resolve

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions