📚 Context

The docstrings in Streamlit's codebase (specifically, the public API) loosely conform to the numpy (aka numpydoc) convention. The specific rules of the numpy convention we follow and don't follow haven't been explicitly laid out.

• What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Refactoring
  • Other, please describe: Doc improvement request

🧠 Description of Changes

This PR does two things:

1. Makes explicit the rules of the numpy convention we follow and those we ignore. Read Error Codes for an exhaustive list of all possible rules.
   • We want to limit ourselves to validate docstrings that are part of Streamlit's public API. However, pydocstyle operates on .py files and not function names. As such, the pre-commit hook in point 2 validates docstrings in .py files in lib/streamlit/ (which contains all .py files corresponding to all public Streamlit commands), excluding lib/streamlit/vendor and lib/streamlit/watcher (both sub dirs don't contain .py files with public API commands).
2. Adds a pre-commit hook that uses pydocstyle to validate if docstrings pass all the rules except the ones mentioned below:

   - repo: https://github.com/pycqa/pydocstyle
       rev: 6.1.1
       hooks:
         - id: pydocstyle
           name: Run pydocstyle
           args:
             - --convention=numpy
             - --add-ignore=D100,D101,D104,D105,D106,D107
             - --add-select=D417
             - --match-dir=(lib\/streamlit\/)(?!vendor)(?!watcher)

Rules we follow

The subset of rules from pydocstyle's Error Codes we follow are:

Rules we ignore

What's not covered in this PR

• All existing docstrings that break any of the above rules we're supposed to follow will not be retroactively fixed. i.e. The pydocstyle pre-commit hook operates only on staged files in git.
  • We choose to operate only on modified files and run the checks locally so as to not disrupt developers' workflows. As a developer contributing to the codebase, one would rather not see hundreds of docstring errors that unrelated to one's contribution; both locally and in CI (GHA)
• The hook does not modify files. It only checks if files follow rules (think linting) and outputs what files, if any, break the rules.

What's next?

The PR ensures that the pydocstyle check will run against any new or modified .py files in (lib\/streamlit\/)(?!vendor)(?!watcher). It leaves unanswered the question: "How do we ensure existing docstrings are validated ?".

That question can be answered using one or both of these options:

1. The Streamlit Documentation team in subsequent PRs fixes all existing the docstrings in violation of rules
2. Let the Community tackle in separate PRs fixes for each violated rule

This PR, however, is independent of the above question and can be merged before it is answered.