# Python Style Guide Update: PEP 8, flake8 & Numpydoc **URL:** \ **Category:** DM Notifications\ **Tags:** doc-engineering, pep8\ **Created:** [September 1, 2016, 4:50pm UTC](https://www.rubin.community/t/python-style-guide-update-pep-8-flake8-numpydoc/1109 "2016-09-01T16:50:34Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [September 1, 2016, 4:50pm UTC](https://www.rubin.community/t/python-style-guide-update-pep-8-flake8-numpydoc/1109/1 "2016-09-01T16:50:34Z")
[Last week](http://www.rubin.community/t/python-style-guide-pep-8-refactor/1086?u=jsick) I mentioned that work was underway to improve the usability of our Python style guide ([RFC-162](https://jira.lsstcorp.org/browse/RFC-162)). This work in [DM-5456](https://jira.lsstcorp.org/browse/DM-5456) is now merged (🎉) and I encourage you to take a look: [https://developer.lsst.io/coding/python\_style\_guide.html](https://developer.lsst.io/coding/python_style_guide.html) With one key exception (numpydoc, see below), nothing about our Python style has changed; we’ve only made it clearer how our style relates to the Python community’s style guide, [PEP 8](https://www.python.org/dev/peps/pep-0008/). If you haven’t already, I encourage you to read through [PEP 8](https://www.python.org/dev/peps/pep-0008/) and then read our [DM Python Style Guide](https://developer.lsst.io/coding/python_style_guide.html) to learn about DM-specific guidelines. ## Flake8 and autopep8 A key feature in the revised [DM Python Style Guide](https://developer.lsst.io/coding/python_style_guide.html) is clear guidance on how to lint your Python for stylistic errors using flake8 and how to automatically fix many style issues with autopep8. See the sections: - [Code MAY be validated with flake8](https://developer.lsst.io/coding/python_style_guide.html#code-may-be-validated-with-flake8) - [autopep8 MAY be used to fix PEP 8 compliance](https://developer.lsst.io/coding/python_style_guide.html#autopep8-may-be-used-to-fix-pep-8-compliance) SQuaRE plans to provide flake8 linting as part of CI ([DM-5637](https://jira.lsstcorp.org/browse/DM-5637)). As flake8 becomes a regular part of our workflow, it becomes important to declare all lines of code that purposefully deviate from the style guide for a good reason. For this, see the guideline: - [Lines that intentionally deviate from DM’s PEP 8 MUST include a noqa comment](https://developer.lsst.io/coding/python_style_guide.html#lines-that-intentionally-deviate-from-dm-s-pep-8-must-include-a-noqa-comment) Props to @parejkoj, @timj and @frossie for the research behind this feature. 👏 ## Numpydoc This style guide update also documents the decision in [RFC-214](https://jira.lsstcorp.org/browse/RFC-214) to officially adopt Numpydoc as the docstring format in all DM Python code. Previously we used Doxygen formatting. For documentation on the Numpydoc format, see: [https://developer.lsst.io/docs/py\_docs.html](https://developer.lsst.io/docs/py_docs.html) ### What does this Numpydoc change mean? [RFC-214](https://jira.lsstcorp.org/browse/RFC-214) has essentially given DM developers permission to use the Numpydoc format for docstrings. That is, you aren’t required to dedicate effort **now** to change all docstrings; rather, you’re allowed to write (or re-write) docstrings in numpydoc so that you won’t need to re-format those docstrings in a month when Sphinx and Numpydoc become our core documentation stack. This does mean that doxygen will be broken for numpydoc’d docstrings. But in [RFC-214](https://jira.lsstcorp.org/browse/RFC-214) we decided this was an acceptable interim state. Also, we haven’t rolled out the capability to render Sphinx/numpydoc documentation for Stack packages. You may end up writing numpydoc docstrings that contain syntax errors. Again, this will only be a temporary problem. I’m already beta-testing the new documentation stack on some packages and it shouldn’t be long before documentation builds are rolled out across the Stack. ### Learning numpydoc The key to Numpydoc is that it specifies a well-defined pattern of sections in reStructuredText. Docstrings for [classes](https://developer.lsst.io/docs/py_docs.html#py-docstring-class-structure), [methods/functions](https://developer.lsst.io/docs/py_docs.html#py-docstring-method-function-structure) and [modules](https://developer.lsst.io/docs/py_docs.html#py-docstring-module-structure) are composed from these sections. The Numpydoc style guide can be a lot to digest in one reading. In the beginning, I recommend that you master the [summary sentence](https://developer.lsst.io/docs/py_docs.html#py-docstring-short-summary), [parameters](https://developer.lsst.io/docs/py_docs.html#py-docstring-parameters), and [returns](https://developer.lsst.io/docs/py_docs.html#py-docstring-returns) sections. This will be sufficient for basic API documentation. Once you’ve mastered this, you can look at incorporating other [sections](https://developer.lsst.io/docs/py_docs.html#common-structure-of-docstrings) into your docstrings. I’m looking into providing some numpydoc tutorials and examples so that we can all work together to build amazing API docs.