validate function/method params against docstrings

[lucas03]

hi, we are using sphinx-apidoc to generate docs

sphinx-apidoc --output-dir docs/kw --no-toc kw && make --directory=docs html

but devs often forget to update docstrings after changing methods/functions. Is there a tool that is able to validate this? I saw stackoverflow question, but no answer there.

Maybe out of scope, but we are at least checking for warnings/errors from sphinx with this CI step:

docs-valid:
  stage: test
  image: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA-py3
  cache:
    key: ${CI_PROJECT_PATH_SLUG}-sphinx
    paths:
      - .doctree/
  script:
    - >
      sphinx-apidoc --output-dir docs/kw --no-toc kw
      && BOOKING_LOGGING_STD_DISABLED=1
      OUTPUT=$(sphinx-build -M html docs docs/_build -q 2>&1 -d .doctree -j 8) || (echo "$OUTPUT"; exit 1);
      echo "$OUTPUT" | grep -E ':[0-9]+: (WARNING|ERROR|SEVERE):' || exit 0;
      echo 'Invalid docstring syntax. Check syntax here -> http://rst.ninjs.org'
      && exit 1

Would be cool if there would be single flag on sphinx-build that would fail on errors/warnings.

[tk0miya]

As I commented to the group, I think this is good proposal for autodoc. +1 for improvement! https://groups.google.com/forum/#!topic/sphinx-users/6gPJzpEXNzk

[saroad2]

+1 for the proposal. Would love to see this feature!