From 523fbb5ecd2e2ce81b4d6b2bf92ba75755f0ebf3 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 1 Dec 2023 11:36:48 -0700 Subject: [PATCH 1/5] updated line length in code contrib section - fix #347 - add note on black --- doc/source/contributing_code.rst | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 6cda9b349..bcced7ddf 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -397,8 +397,8 @@ Code formatting in Python MDAnalysis is a project with a long history and many contributors; it hasn't used a consistent coding style. Since version 0.11.0, we are trying to update all the code to conform with `PEP8`_. Our strategy is to update the style every time we touch an old function and thus switch to `PEP8`_ continuously. -**Important requirements (from PEP8):** - - keep line length to **79 characters or less**; break long lines sensibly +**Important requirements (from PEP8)** (with our own style adapations): + - keep line length to **88 characters or less**; break long lines sensibly - indent with **spaces** and use **4 spaces per level** - naming: @@ -408,8 +408,9 @@ MDAnalysis is a project with a long history and many contributors; it hasn't use We recommend that you use a Python Integrated Development Environment (IDE) (`PyCharm`_ and others) or external tools like `flake8`_ for code linting. For integration of external tools with emacs and vim, check out `elpy`_ (emacs) and `python-mode`_ (vim). To apply the code formatting in an automated way, you can also use code formatters. External tools include `autopep8`_ and `yapf`_. Most IDEs either have their own code formatter or will work with one of the above through plugins. +See :ref:`format-darker` for notes on maintaining code style compliance with existing tools. - + .. _`PEP8`: https://www.python.org/dev/peps/pep-0008/ .. _`flake8`: http://flake8.readthedocs.org/en/latest/ .. _`PyCharm`: https://www.jetbrains.com/pycharm/ @@ -475,7 +476,7 @@ Changes to the code should be reflected in the ongoing ``CHANGELOG``. Add an ent Ensure PEP8 compliance (mandatory) and format your code with Darker (optional) ------------------------------------------------------------------------------- -`Darker `_ is a *partial formatting* tool that helps to reformat new or modified code +`darker`_ is a *partial formatting* tool that helps to reformat new or modified code lines so the codebase progressively adapts a code style instead of doing a full reformat, which would be a big commitment. It was designed with the ``black`` formatter in mind, hence the name. @@ -515,6 +516,20 @@ Or if you're ok with the suggested formatting changes, just apply the suggested darker -r upstream/develop testsuite/MDAnalysisTests -L flake8 +.. note:: + + MDAnalysis does *not* currently use the `black`_ code formatter across the whole project, therefore please consider the following rules: + + * Do **not run ``black`` on an existing file** that you are editing. This makes the diff for the PR very difficult to read. + * You *may* run ``black`` on a *new file* that you are adding to the code base. + + For an ongoing discussion (which you are welcome to join) see `issue #2450`_. + +.. _`darker`: https://github.com/akaihola/darker +.. _`black`: https://black.readthedocs.io/ +.. _`issue #2450`: https://github.com/MDAnalysis/mdanalysis/issues/2450 + + .. _adding-code-to-mda: ------------------------------ From 3f3ac85e457b7f9870d5414a5372be633e8221ce Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 1 Dec 2023 12:49:07 -0700 Subject: [PATCH 2/5] trimmed trailing whitespace --- doc/source/contributing_code.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index bcced7ddf..c8ddad92c 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -410,7 +410,7 @@ We recommend that you use a Python Integrated Development Environment (IDE) (`Py To apply the code formatting in an automated way, you can also use code formatters. External tools include `autopep8`_ and `yapf`_. Most IDEs either have their own code formatter or will work with one of the above through plugins. See :ref:`format-darker` for notes on maintaining code style compliance with existing tools. - + .. _`PEP8`: https://www.python.org/dev/peps/pep-0008/ .. _`flake8`: http://flake8.readthedocs.org/en/latest/ .. _`PyCharm`: https://www.jetbrains.com/pycharm/ @@ -529,7 +529,7 @@ Or if you're ok with the suggested formatting changes, just apply the suggested .. _`black`: https://black.readthedocs.io/ .. _`issue #2450`: https://github.com/MDAnalysis/mdanalysis/issues/2450 - + .. _adding-code-to-mda: ------------------------------ From 9af161c6ef0d1d95bbe819645158411d047c48d6 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 1 Dec 2023 13:14:00 -0700 Subject: [PATCH 3/5] revert back to 79 chars as default --- doc/source/contributing_code.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index c8ddad92c..5fdde3d45 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -397,8 +397,8 @@ Code formatting in Python MDAnalysis is a project with a long history and many contributors; it hasn't used a consistent coding style. Since version 0.11.0, we are trying to update all the code to conform with `PEP8`_. Our strategy is to update the style every time we touch an old function and thus switch to `PEP8`_ continuously. -**Important requirements (from PEP8)** (with our own style adapations): - - keep line length to **88 characters or less**; break long lines sensibly +**Important requirements (from PEP8)**: + - keep line length to **79 characters or less**; break long lines sensibly although for readability we may allow longer lines - indent with **spaces** and use **4 spaces per level** - naming: From b6421c8c76ce6191efbc777d5f39113589882bfb Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 1 Dec 2023 13:17:27 -0700 Subject: [PATCH 4/5] encouraged use of darker instead of black --- doc/source/contributing_code.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 5fdde3d45..05ece7f2f 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -518,9 +518,9 @@ Or if you're ok with the suggested formatting changes, just apply the suggested .. note:: - MDAnalysis does *not* currently use the `black`_ code formatter across the whole project, therefore please consider the following rules: + MDAnalysis does *not* currently use the popular `black`_ code formatter across the whole project, therefore please consider the following rules: - * Do **not run ``black`` on an existing file** that you are editing. This makes the diff for the PR very difficult to read. + * Do **not run ``black`` on an existing file** that you are editing. This makes the diff for the PR very difficult to read. Instead use ``darker`` as explained above to only reformat your changes. * You *may* run ``black`` on a *new file* that you are adding to the code base. For an ongoing discussion (which you are welcome to join) see `issue #2450`_. From b4fd7a02e9820dbea5c2ee2a3b5b963ca74aa775 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 12 Jan 2024 17:04:33 -0700 Subject: [PATCH 5/5] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 05ece7f2f..65bc8c987 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -520,7 +520,7 @@ Or if you're ok with the suggested formatting changes, just apply the suggested MDAnalysis does *not* currently use the popular `black`_ code formatter across the whole project, therefore please consider the following rules: - * Do **not run ``black`` on an existing file** that you are editing. This makes the diff for the PR very difficult to read. Instead use ``darker`` as explained above to only reformat your changes. + * **Do not run** ``black`` on an existing file that you are editing. This makes the diff for the PR very difficult to read. Instead use ``darker`` as explained above to only reformat your changes. * You *may* run ``black`` on a *new file* that you are adding to the code base. For an ongoing discussion (which you are welcome to join) see `issue #2450`_.