Adopt pre-commit (#1744)

.pre-commit-config.yaml

@@ -0,0 +1,69 @@
+ci:
+  skip: [check-jsonschema]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+  #     - id: end-of-file-fixer
+  #     - id: check-case-conflict
+  #     - id: check-executables-have-shebangs
+  #     - id: requirements-txt-fixer
+      - id: check-added-large-files
+  #     - id: check-case-conflict
+  #     - id: check-toml
+  #     - id: check-yaml
+  #     - id: debug-statements
+  #     - id: forbid-new-submodules
+  #     - id: check-builtin-literals
+  #     - id: trailing-whitespace
+
+  # - repo: https://github.com/psf/black
+  #   rev: 22.3.0
+  #   hooks:
+  #     - id: black
+  #       args: ["--line-length", "100"]
+
+  # - repo: https://github.com/PyCQA/isort
+  #   rev: 5.10.1
+  #   hooks:
+  #     - id: isort
+  #       files: \.py$
+  #       args: [--profile=black]
+
+  # - repo: https://github.com/pre-commit/mirrors-prettier
+  #   rev: v2.6.1
+  #   hooks:
+  #     - id: prettier
+
+  # - repo: https://github.com/asottile/pyupgrade
+  #   rev: v2.31.1
+  #   hooks:
+  #     - id: pyupgrade
+  #       args: [--py37-plus]
+
+  - repo: https://github.com/PyCQA/doc8
+    rev: 0.11.0
+    hooks:
+      - id: doc8
+        args: [--max-line-length=200]
+
+  # - repo: https://github.com/pycqa/flake8
+  #   rev: 4.0.1
+  #   hooks:
+  #     - id: flake8
+  #       additional_dependencies:
+  #         [
+  #           "flake8-bugbear==20.1.4",
+  #           "flake8-logging-format==0.6.0",
+  #           "flake8-implicit-str-concat==0.2.0",
+  #         ]
+
+  - repo: https://github.com/sirosen/check-jsonschema
+    rev: 0.14.1
+    hooks:
+      - id: check-jsonschema
+        name: "Check GitHub Workflows"
+        files: ^\.github/workflows/
+        types: [yaml]
+        args: ["--schemafile", "https://json.schemastore.org/github-workflow"]

CONTRIBUTING.md

@@ -4,7 +4,7 @@ We follow the
 [Jupyter Contribution Workflow](https://jupyter.readthedocs.io/en/latest/contributing/content-contributor.html)
 and the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
 
-# Testing
+## Testing
 
 In order to test all the features of nbconvert you need to have `pandoc` and
 `TexLive` installed. 
@@ -14,7 +14,7 @@ run all of the tests and to test all of the features.
 
 If you only want to run some of the tests run `pip install -e '.[test]'`.
 
-# Documentation
+## Documentation
 
 NbConvert includes a substantial amount of both user and API documentation. 
 
@@ -32,6 +32,38 @@ the standard dependencies. You can get all of the dependencies by running `pip i
 
 Full build instructions can be found at [docs/README.md](docs/README.md).
 
+
+## Code Styling
+`nbconvert` has adopted automatic code formatting so you shouldn't
+need to worry too much about your code style.
+As long as your code is valid,
+the pre-commit hook should take care of how it should look.
+`pre-commit` and its associated hooks will automatically be installed when
+you run `pip install -e ".[test]"`
+
+To install `pre-commit` manually, run the following:
+
+```bash
+pip install pre-commit
+pre-commit install
+````
+
+You can invoke the pre-commit hook by hand at any time with:
+
+```bash
+pre-commit run
+````
+
+which should run any autoformatting on your code
+and tell you about any errors it couldn't fix automatically.
+You may also install [black integration](https://github.com/psf/black#editor-integration)
+into your text editor to format code automatically.
+
+If you have already committed files before setting up the pre-commit
+hook with `pre-commit install`, you can fix everything up using
+`pre-commit run --all-files`. You need to make the fixing commit
+yourself after that.
+
 # Releasing
 
 If you are going to release a version of `nbconvert` you should also be capable

MANIFEST.in

@@ -11,6 +11,8 @@ graft docs
 exclude docs/\#*
 exclude .readthedocs.yml
 exclude codecov.yml
+exclude .pre-commit-config.yaml
+exclude .git-blame-ignore-revs
 
 # Examples
 graft examples

docs/source/api/nbconvertapp.rst

@@ -22,4 +22,4 @@ NbConvertApp
 
     .. automethod:: write_single_notebook
 
-    .. automethod:: postprocess_single_notebook
+    .. automethod:: postprocess_single_notebook

docs/source/api/writers.rst

@@ -21,4 +21,4 @@ Specialized writers
 
 .. autoclass:: FilesWriter
 
-.. autoclass:: StdoutWriter
+.. autoclass:: StdoutWriter

docs/source/architecture.rst

@@ -19,7 +19,9 @@ Nbconvert takes in a notebook, which is a JSON object, and operates on that obje
 This can include operations that take a notebook and return a notebook.
 For example, that operation could be to execute the notebook as though it were a continuous script; if it were executed ``--in-place`` then it would overwrite the current notebook.
 Or it could be that we wish to systematically alter the notebook, for example by clearing all output cells.
-Format agnostic operations on cell content that do not violate the nbformat spec can be interpreted as a notebook to notebook conversion step; such operations can be performed as part of the preprocessing step.
+Format agnostic operations on cell content that do not violate the nbformat
+spec can be interpreted as a notebook to notebook conversion step; such
+operations can be performed as part of the preprocessing step.
 
 But often we want to have the notebook's structured content in a different format.
 Importantly, in many cases the structure of the notebook should be reflected in the structure of the output, adapted to the output's format.