Add pre-commit hook / linter (#374)

* Add pre-commit hook / linter

* Run linter

* Fix GH workflow

Author: jarrodmillman

.circleci/config.yml

@@ -1,44 +1,44 @@
 version: 2
 jobs:
-    build_docs:
-      docker:
-        - image: circleci/python:3.7-stretch
-      steps:
-        - checkout
-        - run:
-            name: Set BASH_ENV
-            command: |
-              echo "set -e" >> $BASH_ENV;
-              echo "export PATH=~/.local/bin:$PATH" >> $BASH_ENV;
-              sudo apt update
-              sudo apt install dvipng texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra texlive-generic-extra latexmk texlive-xetex
-        - restore_cache:
-            keys:
-              - pip-cache
-        - run:
-            name: Get dependencies and install
-            command: |
-              pip install --user -q --upgrade pip setuptools
-              pip install --user -q --upgrade numpy matplotlib sphinx pydata-sphinx-theme
-              pip install --user -e .
-        - save_cache:
-            key: pip-cache
-            paths:
-              - ~/.cache/pip
-        - run:
-            name: make html
-            command: |
-              make -C doc html
-        - store_artifacts:
-            path: doc/_build/html/
-            destination: html
-        - run:
-            name: make tinybuild
-            command: |
-              make -C numpydoc/tests/tinybuild html
-        - store_artifacts:
-            path: numpydoc/tests/tinybuild/_build/html/
-            destination: tinybuild
+  build_docs:
+    docker:
+      - image: circleci/python:3.7-stretch
+    steps:
+      - checkout
+      - run:
+          name: Set BASH_ENV
+          command: |
+            echo "set -e" >> $BASH_ENV;
+            echo "export PATH=~/.local/bin:$PATH" >> $BASH_ENV;
+            sudo apt update
+            sudo apt install dvipng texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra texlive-generic-extra latexmk texlive-xetex
+      - restore_cache:
+          keys:
+            - pip-cache
+      - run:
+          name: Get dependencies and install
+          command: |
+            pip install --user -q --upgrade pip setuptools
+            pip install --user -q --upgrade numpy matplotlib sphinx pydata-sphinx-theme
+            pip install --user -e .
+      - save_cache:
+          key: pip-cache
+          paths:
+            - ~/.cache/pip
+      - run:
+          name: make html
+          command: |
+            make -C doc html
+      - store_artifacts:
+          path: doc/_build/html/
+          destination: html
+      - run:
+          name: make tinybuild
+          command: |
+            make -C numpydoc/tests/tinybuild html
+      - store_artifacts:
+          path: numpydoc/tests/tinybuild/_build/html/
+          destination: tinybuild
 
 workflows:
   version: 2

.github/workflows/lint.yml

@@ -0,0 +1,12 @@
+name: style
+
+on: [push, pull_request]
+
+jobs:
+  pre-commit:
+    name: Linting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - uses: pre-commit/[email protected]

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: numpydoc tests
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   test:
@@ -15,48 +15,48 @@ jobs:
         python-version: ["3.7", "3.8", "3.9", "3.10"]
         sphinx-version: ["sphinx==1.8.0", "sphinx==2.1", "sphinx>3.0"]
     steps:
-    - uses: actions/checkout@v2
-    
-    - name: Python setup
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Setup environment
-      run: |
-        python -m venv venv
-        source venv/bin/activate
-
-    - name: Install
-      run: |
-        python -m pip install --upgrade pip wheel setuptools
-        python -m pip install -r test_requirements.txt -r doc/requirements.txt
-        python -m pip install codecov
-        python -m pip install ${{ matrix.sphinx-version }}
-        python -m pip install .
-        pip list
-
-    - name: Run test suite
-      run: |
-        pytest -v --pyargs .
-
-    - name: Test coverage
-      run: |
-        codecov
-
-    - name: Make sure CLI works
-      run: |
-        python -m numpydoc numpydoc.tests.test_main._capture_stdout
-        echo '! python -m numpydoc numpydoc.tests.test_main._invalid_docstring' | bash
-        python -m numpydoc --validate numpydoc.tests.test_main._capture_stdout
-        echo '! python -m numpydoc --validate numpydoc.tests.test_main._docstring_with_errors' | bash
-
-    - name: Setup for doc build
-      run: |
-        sudo apt-get update
-        sudo apt install texlive texlive-latex-extra latexmk dvipng
-
-    - name: Build documentation
-      run: |
-        make -C doc html SPHINXOPTS="-nT"
-        make -C doc latexpdf SPHINXOPTS="-nT"
+      - uses: actions/checkout@v2
+
+      - name: Python setup
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup environment
+        run: |
+          python -m venv venv
+          source venv/bin/activate
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -r requirements/test.txt -r doc/requirements.txt
+          python -m pip install codecov
+          python -m pip install ${{ matrix.sphinx-version }}
+          python -m pip install .
+          pip list
+
+      - name: Run test suite
+        run: |
+          pytest -v --pyargs .
+
+      - name: Test coverage
+        run: |
+          codecov
+
+      - name: Make sure CLI works
+        run: |
+          python -m numpydoc numpydoc.tests.test_main._capture_stdout
+          echo '! python -m numpydoc numpydoc.tests.test_main._invalid_docstring' | bash
+          python -m numpydoc --validate numpydoc.tests.test_main._capture_stdout
+          echo '! python -m numpydoc --validate numpydoc.tests.test_main._docstring_with_errors' | bash
+
+      - name: Setup for doc build
+        run: |
+          sudo apt-get update
+          sudo apt install texlive texlive-latex-extra latexmk dvipng
+
+      - name: Build documentation
+        run: |
+          make -C doc html SPHINXOPTS="-nT"
+          make -C doc latexpdf SPHINXOPTS="-nT"

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+# Install pre-commit hooks via
+# pre-commit install
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: debug-statements
+      - id: check-ast
+      - id: mixed-line-ending
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v2.6.2
+    hooks:
+      - id: prettier
+        files: \.(html|md|yml|yaml)
+        args: [--prose-wrap=preserve]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.31.1
+    hooks:
+      - id: pyupgrade
+        args: [--py37-plus]

doc/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # project-template documentation build configuration file, created by
 # sphinx-quickstart on Mon Jan 18 14:44:12 2016.
@@ -61,7 +60,7 @@
 master_doc = 'index'  # NOTE: will be changed to `root_doc` in sphinx 4
 
 # General information about the project.
-project = u'numpydoc'
+project = 'numpydoc'
 copyright = f'2019-{date.today().year}, numpydoc maintainers'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -209,8 +208,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', 'numpydoc.tex', u'numpydoc Documentation',
-     u'Numpydoc maintainers', 'manual'),
+    ('index', 'numpydoc.tex', 'numpydoc Documentation',
+     'Numpydoc maintainers', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

doc/example.py

@@ -9,7 +9,6 @@
 a line by itself, preferably preceded by a blank line.
 
 """
-from __future__ import division, absolute_import, print_function
 
 import os  # standard library imports first
 

numpydoc/docscrape.py

@@ -378,7 +378,7 @@ def _parse(self):
         self._parse_summary()
 
         sections = list(self._read_sections())
-        section_names = set([section for section, content in sections])
+        section_names = {section for section, content in sections}
 
         has_returns = 'Returns' in section_names
         has_yields = 'Yields' in section_names

numpydoc/docscrape_sphinx.py

@@ -268,7 +268,7 @@ def _str_member_list(self, name):
                 out += [''] + autosum
 
             if others:
-                maxlen_0 = max(3, max([len(p.name) + 4 for p in others]))
+                maxlen_0 = max(3, max(len(p.name) + 4 for p in others))
                 hdr = "=" * maxlen_0 + "  " + "=" * 10
                 fmt = '%%%ds  %%s  ' % (maxlen_0,)
                 out += ['', '', hdr]
@@ -382,7 +382,7 @@ def __str__(self, indent=0, func_role="obj"):
                 else self._str_member_list('Attributes'),
             'methods': self._str_member_list('Methods'),
         }
-        ns = dict((k, '\n'.join(v)) for k, v in ns.items())
+        ns = {k: '\n'.join(v) for k, v in ns.items()}
 
         rendered = self.template.render(**ns)
         return '\n'.join(self._str_indent(rendered.split('\n'), indent))

numpydoc/tests/test_docscrape.py

@@ -1,4 +1,3 @@
-# -*- encoding:utf-8 -*-
 from collections import namedtuple
 from copy import deepcopy
 import re

numpydoc/tests/test_full.py

@@ -41,12 +41,12 @@ def test_MyClass(sphinx_app):
     src_dir, out_dir = sphinx_app.srcdir, sphinx_app.outdir
     class_rst = op.join(src_dir, 'generated',
                         'numpydoc_test_module.MyClass.rst')
-    with open(class_rst, 'r') as fid:
+    with open(class_rst) as fid:
         rst = fid.read()
     assert r'numpydoc\_test\_module' in rst  # properly escaped
     class_html = op.join(out_dir, 'generated',
                          'numpydoc_test_module.MyClass.html')
-    with open(class_html, 'r') as fid:
+    with open(class_html) as fid:
         html = fid.read()
     # ensure that no autodoc weirdness ($) occurs
     assert '$self' not in html
@@ -66,7 +66,7 @@ def test_my_function(sphinx_app):
     out_dir = sphinx_app.outdir
     function_html = op.join(out_dir, 'generated',
                             'numpydoc_test_module.my_function.html')
-    with open(function_html, 'r') as fid:
+    with open(function_html) as fid:
         html = fid.read()
     assert r'\*args' not in html
     assert '*args' in html
@@ -83,7 +83,7 @@ def test_reference(sphinx_app, html_file, expected_length):
     """Test for bad references"""
     out_dir = sphinx_app.outdir
 
-    with open(op.join(out_dir, *html_file), 'r') as fid:
+    with open(op.join(out_dir, *html_file)) as fid:
         html = fid.read()
 
     reference_list = re.findall(r'<a class="fn-backref" href="\#id\d+">(.*)<\/a>', html)

numpydoc/tests/test_numpydoc.py

@@ -1,4 +1,3 @@
-# -*- encoding:utf-8 -*-
 import pytest
 from io import StringIO
 from copy import deepcopy
@@ -123,9 +122,9 @@ def _function_without_seealso_and_examples():
         # Validation configured off - expect no warnings
         (set(), [], []),
         # Validation on with expected warnings
-        (set(['SA01', 'EX01']), ('SA01', 'EX01'), []),
+        ({'SA01', 'EX01'}, ('SA01', 'EX01'), []),
         # Validation on with only one activated check
-        (set(['SA01']), ('SA01',), ('EX01',)),
+        ({'SA01'}, ('SA01',), ('EX01',)),
     ),
 )
 def test_mangle_docstring_validation_warnings(
@@ -190,7 +189,7 @@ def test_update_config_exclude_str():
     app = MockApp()
     app.config.numpydoc_validation_checks = set()
     app.config.numpydoc_validation_exclude = "shouldnt-be-a-str"
-    with pytest.raises(ValueError, match="\['shouldnt-be-a-str'\]"):
+    with pytest.raises(ValueError, match=r"\['shouldnt-be-a-str'\]"):
         update_config(app)
 
 

numpydoc/tests/test_xref.py

@@ -1,4 +1,3 @@
-# -*- encoding:utf-8 -*-
 import pytest
 from numpydoc.xref import make_xref, DEFAULT_LINKS
 

requirements/developer.txt

@@ -0,0 +1 @@
+pre-commit>=2.18

test_requirements.txt renamed to requirements/test.txt

@@ -47,7 +47,7 @@ def read(fname):
     python_requires=">=3.7",
     extras_require={
         "testing": [
-            req for req in read('test_requirements.txt').split('\n')
+            req for req in read('requirements/test.txt').split('\n')
             if not req.startswith('#')
         ],
     },