3

We're building our documentation using Sphinx v3 with Read the Docs using sphinx.ext.napoleon and Google-style docstrings. When we build locally, Sphinx doesn't catch badly-formatted Google docstrings as warnings. For example:

"""
This should go next to the triple quotes above.

Args: there should be nothing here
    sample_arg (int): there also shouldn't be anything here
    Some documentation that is missing a tab at the beginning.

Missing return
"""

Building locally with make html, this does not throw any warnings but horribly screws up how this appears on readthedocs. We have added sphinx.ext.napoleon in our conf.py extensions variable and have kept the original Makefile as is except for adding the flags -W --keep-going -a -E under SPHINXOPTS.

Is there a way to get Sphinx to fail the build if someone tries to run make build with bad Google-style documentation? Or do we have to live with manually looking through and identifying these errors?

user4793385
  • 145
  • 5
  • If you're referring to the Google Python Style Guide, your example is wrong in two places. First, where it says "there also shouldn't be anything here" is where you should put the documentation for `sample_arg`. Second, where it says "Some documentation that is missing a tab at the beginning," the official example has a two-space hanging indent. See [the style guide](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). – Brian McCutchon Sep 01 '20 at 21:17
  • 1
    @Brian McCutchon Maybe I should've phrased the question better. I'm not asking whether the example I provided is right. It was intentionally formatted wrong and I forgot to list a few other errors such as the one you mentioned. I'm asking if there is a way to configure Sphinx to catch those styling errors. Currently, running ```make build``` doesn't list any of these as warnings while building the documentation wrong. – user4793385 Sep 01 '20 at 21:34
  • Perhaps there is a linter similar to [pydocstyle](https://github.com/PyCQA/pydocstyle) or [pylint](https://pylint.org/), or a formatter similar to Black but for Google-style docstrings? I don't know of any Sphinx extension that can do what you want, other than what is provided with [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc) and [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon). – Steve Piercy Sep 02 '20 at 04:54
  • 1
    pydocstyle now supports google-style: http://www.pydocstyle.org/en/stable/error_codes.html?highlight=google#default-conventions can also be used via the flake8 plugin [flake8-docstrings](https://pypi.org/project/flake8-docstrings/) – Stan Jul 15 '22 at 12:37

0 Answers0