1419772 - [docs] Enable sphinx.ext.napoleon for more readable docstrings

Status: RESOLVED FIXED

(Firefox Build System :: General, enhancement)

Description

[Andrew Halberstadt [:ahal]]

http://www.sphinx-doc.org/en/stable/ext/napoleon.html

This will allow us to use either the Google or numpy style guide for docstrings which tend to be more human readable than the standard sphinx format.

Comment 1

[Andrew Halberstadt [:ahal]]

Attachment: Bug 1419772 - [docs] Enable the sphinx.ext.napoleon extension,

This enables sphinx to parse both the google and numpy style docstring
formats which tend to be more human readable than the default sphinx
format.

See:
http://www.sphinx-doc.org/en/stable/ext/napoleon.html

Review commit: https://reviewboard.mozilla.org/r/202052/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/202052/

Comment 2

[Tom Prince [:tomprince]]

I think consistency over the codebase is more important than any particular style of docstring.

Comment 3

[Andrew Halberstadt [:ahal]]

I half agree, mozilla-central is a repository of many projects. While I do think each "project" should be consistent within itself, I don't agree that we should enforce a particular style across the board. For example, we allow projects to specify their own custom .flake8 configs for linting.

That said, I do think a linter that enforces at least some kind of docstring consistency (which can maybe be configured to the preferred style per-project), would be a good idea.

Comment 4

[Gregory Szorc [:gps]]

Comment on attachment 8930963 [details]
Bug 1419772 - [docs] Enable the sphinx.ext.napoleon extension,

https://reviewboard.mozilla.org/r/202052/#review207486

Comment 5

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/7cc1270bf794
[docs] Enable the sphinx.ext.napoleon extension, r=gps

Comment 6

[Stefan Hindli [:stefan_hindli]]

https://hg.mozilla.org/mozilla-central/rev/7cc1270bf794