diff --git a/doc/source/development/code_style.rst b/doc/source/development/code_style.rst index 5aa1c1099d6e0..9477a9ac79dd6 100644 --- a/doc/source/development/code_style.rst +++ b/doc/source/development/code_style.rst @@ -12,8 +12,9 @@ pandas code style guide pandas follows the `PEP8 `_ standard and uses `Black `_ and `Flake8 `_ to ensure a -consistent code format throughout the project. For details see the -:ref:`contributing guide to pandas`. +consistent code format throughout the project. We encourage you to use +:ref:`pre-commit ` to automatically run ``black``, +``flake8``, ``isort``, and related code checks when you make a git commit. Patterns ======== diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst index 08d8451127732..4261d79a5e3f5 100644 --- a/doc/source/development/contributing.rst +++ b/doc/source/development/contributing.rst @@ -638,7 +638,46 @@ In addition to ``./ci/code_checks.sh``, some extra checks are run by ``pre-commit`` - see :ref:`here ` for how to run them. -Additional standards are outlined on the :ref:`pandas code style guide ` +Additional standards are outlined on the :ref:`pandas code style guide `. + +.. _contributing.pre-commit: + +Pre-commit +---------- + +You can run many of these styling checks manually as we have described above. However, +we encourage you to use `pre-commit hooks `_ instead +to automatically run ``black``, ``flake8``, ``isort`` when you make a git commit. This +can be done by installing ``pre-commit``:: + + pip install pre-commit + +and then running:: + + pre-commit install + +from the root of the pandas repository. Now all of the styling checks will be +run each time you commit changes without your needing to run each one manually. +In addition, using ``pre-commit`` will also allow you to more easily +remain up-to-date with our code checks as they change. + +Note that if needed, you can skip these checks with ``git commit --no-verify``. + +If you don't want to use ``pre-commit`` as part of your workflow, you can still use it +to run its checks with:: + + pre-commit run --files + +without needing to have done ``pre-commit install`` beforehand. + +.. note:: + + If you have conflicting installations of ``virtualenv``, then you may get an + error - see `here `_. + + Also, due to a `bug in virtualenv `_, + you may run into issues if you're using conda. To solve this, you can downgrade + ``virtualenv`` to version ``20.0.33``. Optional dependencies --------------------- @@ -712,7 +751,7 @@ Python (PEP8 / black) pandas follows the `PEP8 `_ standard and uses `Black `_ and `Flake8 `_ to ensure a consistent code -format throughout the project. +format throughout the project. We encourage you to use :ref:`pre-commit `. :ref:`Continuous Integration ` will run those tools and report any stylistic errors in your code. Therefore, it is helpful before @@ -727,9 +766,6 @@ apply ``black`` as you edit files. You should use a ``black`` version 20.8b1 as previous versions are not compatible with the pandas codebase. -If you wish to run these checks automatically, we encourage you to use -:ref:`pre-commits ` instead. - One caveat about ``git diff upstream/master -u -- "*.py" | flake8 --diff``: this command will catch any stylistic errors in your changes specifically, but be beware it may not catch all of them. For example, if you delete the only @@ -807,45 +843,6 @@ Where similar caveats apply if you are on OSX or Windows. You can then verify the changes look ok, then git :ref:`commit ` and :ref:`push `. -.. _contributing.pre-commit: - -Pre-commit -~~~~~~~~~~ - -You can run many of these styling checks manually as we have described above. However, -we encourage you to use `pre-commit hooks `_ instead -to automatically run ``black``, ``flake8``, ``isort`` when you make a git commit. This -can be done by installing ``pre-commit``:: - - pip install pre-commit - -and then running:: - - pre-commit install - -from the root of the pandas repository. Now all of the styling checks will be -run each time you commit changes without your needing to run each one manually. -In addition, using this pre-commit hook will also allow you to more easily -remain up-to-date with our code checks as they change. - -Note that if needed, you can skip these checks with ``git commit --no-verify``. - -If you don't want to use ``pre-commit`` as part of your workflow, you can still use it -to run its checks by running:: - - pre-commit run --files - -without having to have done ``pre-commit install`` beforehand. - -.. note:: - - If you have conflicting installations of ``virtualenv``, then you may get an - error - see `here `_. - - Also, due to a `bug in virtualenv `_, - you may run into issues if you're using conda. To solve this, you can downgrade - ``virtualenv`` to version ``20.0.33``. - Backwards compatibility ~~~~~~~~~~~~~~~~~~~~~~~