docs: Adding section on Ruff in code style tools page (#592)

* docs: Adding section on Ruff in code style tools page

* docs: Removing sections on Black, isort and Flake8 in code style tools page

* docs: Updating based on review comments

* docs: Harmonising documentation with changes made to code style tool page

* docs: Updating required-standard based on review comment

* Update doc/source/coding-style/required-standard.rst

---------

Co-authored-by: Sébastien Morais <[email protected]>

Author: ecoussoux-ansys

doc/source/coding-style/formatting-tools.rst

@@ -11,92 +11,68 @@ Most of the tools presented can be configured using :ref:`the
 \`\`pyproject.toml\`\` file`. Avoiding dotfiles leads to a much
 cleaner root project directory.
 
-Black
------
+Ruff
+----
 
-`Black`_ is the most popular code formatter in the Python community because it is
-maintained by the Python Software Foundation. It allows for a minimum
-configuration to ensure that the Python code format looks almost the same across
-projects. 
+`Ruff`_ is a Python linter and code formatter written in Rust. It aims to be 
+orders of magnitude faster than alternative tools while integrating more 
+functionality behind a single, common interface. Ruff can therefore be used 
+to replace the previously preferred alternatives that were `Flake8`_ 
+(natively re-implementing its popular plugins), `Black`_ and `isort`_.
 
-While `PEP 8`_ imposes a default line length of 79 characters, Black has
-a default line length of 88 characters.
+It is actively developed, used in major open-source projects, and offers the following 
+features and advantages:
 
-The minimum Black configuration for a PyAnsys project should look like this:
+- Can be installed via ``pip install ruff``
 
-.. code-block:: toml
-
-    [tool.black]
-    line-length = "<length>"
-
-
-The ``isort`` tool
-------------------
-
-The goal of `isort`_  is to properly format ``import`` statements by making sure
-that they follow the standard order:
-
-#. Library
-#. Third-party libraries
-#. Custom libraries
+- ``pyproject.toml`` support
 
-When using `isort`_ with `Black`_, it is important to properly configure both
-tools so that no conflicts arise. To accomplish this, use the
-``--profile black`` flag in ``isort``.
+- Python 3.7 to 3.13 compatibility
 
-.. code-block:: toml
-
-   [tool.isort]
-   profile = "black"
-   force_sort_within_sections = true
-   line_length = "<length>"
-   src_paths = ["doc", "src", "tests"]
-
-Flake8
-------
+- Built-in caching, to avoid re-analyzing unchanged files
 
-The goal of `Flake8`_ is to act as a `PEP 8`_ compliance checker. Again, if
-this tool is being used with `Black`_, it is important to make sure that no
-conflicts arise.
+- Over 800 built-in rules
 
-The following configuration is the minimum one to set up Flake8 together with
-Black.
+- Editor integrations for VS Code or PyCharm
 
-The configuration for Flake8 must be specified in a ``.flake8`` file.
+A minimum Ruff configuration for a PyAnsys project (to be included in the ``pyproject.toml``)
+may look like this:
 
 .. code-block:: toml
 
-   [flake8]
-   max-line-length = 88
-   extend-ignore = 'E203'
-
-Flake8 has many options that can be set within the configuration file.
-For more information, see `Full Listing of Options and Their Descriptions
-<https://flake8.pycqa.org/en/latest/user/options.html>`__ in the Flake8
-documentation.
-
-The example configuration defines these options:
-
-- ``exclude``
-    Subdirectories and files to exclude when checking.
-
-- ``select``
-    Sequence of error codes that Flake8 is to report errors
-    for. The set in the preceding configuration is a basic set of errors
-    for checking and is not an exhaustive list. For more information, see
-    `Error/Violation Codes <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html>`__
-    in the Flake8 documentation.
-
-- ``count``
-    Total number of errors to print when checking ends.
-
-- ``max-complexity``
-    Maximum allowed McCabe complexity value for a block of code.
-    The value of 10 was chosen because it is a common default.
-
-- ``statistics``
-    Number of occurrences of each error or warning code
-    to print as a report when checking ends.
+    [tool.ruff]
+    line-length = 100
+    fix = true
+
+    [tool.ruff.format]
+    quote-style = "double"
+    indent-style = "space"
+
+    [tool.ruff.lint]
+    select = [
+        "E",    # pycodestyle, see https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+        "D",    # pydocstyle, see https://docs.astral.sh/ruff/rules/#pydocstyle-d
+        "F",    # pyflakes, see https://docs.astral.sh/ruff/rules/#pyflakes-f
+        "I",    # isort, see https://docs.astral.sh/ruff/rules/#isort-i
+        "N",    # pep8-naming, see https://docs.astral.sh/ruff/rules/#pep8-naming-n
+        "PTH",  # flake8-use-pathlib, https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+        "TD",   # flake8-todos, https://docs.astral.sh/ruff/rules/#flake8-todos-td
+    ]
+    ignore = [
+        "TD003", # Missing issue link in TODOs comment
+    ]
+
+    [tool.ruff.lint.pydocstyle]
+    convention = "numpy"
+
+    [tool.ruff.lint.isort]
+    combine-as-imports = true
+    force-sort-within-sections = true
+
+Linting and formatting rules shall be added step by step when migrating a project to Ruff, 
+gradually resolving the triggered errors. For more information about configuring Ruff, as 
+well as a complete description of the available rules and settings, please refer to the 
+`tool's documentation <https://docs.astral.sh/ruff/configuration/>`__.
 
 
 The ``Add-license-headers`` pre-commit hook
@@ -151,20 +127,11 @@ configuration that includes both code and documentation formatting tools.
 
     repos:
     
-    - repo: https://github.com/psf/black
-      rev: X.Y.Z
-      hooks:
-      - id: black
-    
-    - repo: https://github.com/pycqa/isort
-      rev: X.Y.Z
-      hooks:
-      - id: isort
-    
-    - repo: https://github.com/PyCQA/flake8
-      rev: X.Y.Z
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: vX.Y.Z
       hooks:
-      - id: flake8
+      - id: ruff
+      - id: ruff-format
     
     - repo: https://github.com/codespell-project/codespell
       rev: vX.Y.Z

doc/source/coding-style/required-standard.rst

@@ -13,15 +13,33 @@ Required ``pyproject.toml`` file configuration
 
 .. code-block:: toml
 
-    [tool.black]
-    line-length = "<length>"
-
-    [tool.isort]
-    profile = "black"
-    force_sort_within_sections = true
-    line_length = "<length>"
-    src_paths = ["doc", "src", "tests"]
+    [tool.ruff]
+    line-length = 100
+    fix = true
+
+    [tool.ruff.format]
+    quote-style = "double"
+    indent-style = "space"
+
+    [tool.ruff.lint]
+    select = [
+        "E",    # pycodestyle, see https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+        "D",    # pydocstyle, see https://docs.astral.sh/ruff/rules/#pydocstyle-d
+        "F",    # pyflakes, see https://docs.astral.sh/ruff/rules/#pyflakes-f
+        "I",    # isort, see https://docs.astral.sh/ruff/rules/#isort-i
+        "N",    # pep8-naming, see https://docs.astral.sh/ruff/rules/#pep8-naming-n
+        "PTH",  # flake8-use-pathlib, https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+        "TD",   # flake8-todos, https://docs.astral.sh/ruff/rules/#flake8-todos-td
+    ]
+    ignore = []
+
+    [tool.ruff.lint.pydocstyle]
+    convention = "numpy"
 
+    [tool.ruff.lint.isort]
+    combine-as-imports = true
+    force-sort-within-sections = true
+    
     [tool.coverage.run]
     source = ["ansys.<product>"]
 
@@ -34,17 +52,6 @@ Required ``pyproject.toml`` file configuration
     [tool.pydocstyle]
     convention = "numpy"
 
-Required flake8 configuration
------------------------------
-
-The following ``.flake8`` file is also required:
-
-.. code-block:: toml
-
-   [flake8]
-   max-line-length = 88
-   extend-ignore = 'E203'
-
 Required ``pre-commit`` configuration
 -------------------------------------
 
@@ -54,22 +61,13 @@ You can take advantage of `pre-commit`_ by including a
 .. code-block:: yaml
 
     repos:
-
-    - repo: https://github.com/psf/black
-      rev: X.Y.Z
-      hooks:
-      - id: black
-    
-    - repo: https://github.com/pycqa/isort
-      rev: X.Y.Z
-      hooks:
-      - id: isort
     
-    - repo: https://github.com/PyCQA/flake8
-      rev: X.Y.Z
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: vX.Y.Z
       hooks:
-      - id: flake8
-    
+      - id: ruff
+      - id: ruff-format
+
     - repo: https://github.com/codespell-project/codespell
       rev: vX.Y.Z
       hooks:

doc/source/content-writing/content-how-tos/create-PR.rst

@@ -28,10 +28,10 @@ Run pre-commit locally
 
 `pre-commit <pre-commit_>`_ is a tool for ensuring that all the changes that you make to
 files in your project successfully pass all checks run by the code style tools that are
-configured as part of the CI/CD process. These tools, which typically include `Black <Black_>`_,
-`isort <isort_>`_, and `Flake8 <Flake8_>`_, analyze, format, review, and improve
-code quality and security. For more information on the code style tools most commonly
-configured for use in PyAnsys projects, see :ref:`code_style_tools`.
+configured as part of the CI/CD process. These tools, which typically include `Ruff`_, 
+analyze, format, review, and improve code quality and security. For more information on 
+the code style tools most commonly configured for use in PyAnsys projects, 
+see :ref:`code_style_tools`.
 
 Because you do not want the **Code style** check for your PyAnsys project to fail
 when you create or push changes to a PR, you want to periodically run ``pre-commit``

doc/source/content-writing/content-how-tos/resolve-issues-causing-check-failures.rst

@@ -99,11 +99,11 @@ Actions that you might take include these:
 Resolve too long line lengths and broken links
 ----------------------------------------------
 
-In PyAnsys projects, `Flake8 <Flake8_>`_ is a code style tool in the CI/CD process
-that checks the quality of the Python code. When you run ``pre-commit`` locally,
-Flake8 is one of the tools that it is configured to run. If Flake8 finds a line in a
-Python file that is too long, it raises an error. Providing that this line is a
-docstring or message string, you can manually change it in the PY file.
+In PyAnsys projects, `Ruff`_ is a code style tool in the CI/CD process that checks the 
+quality of the Python code. When you run ``pre-commit`` locally, Ruff is one of the tools 
+that it is configured to run. If Ruff finds a line in a Python file that is too long, 
+it raises an error. Providing that this line is a docstring or message string, you can 
+manually change it in the PY file.
 
 Sometimes, however, the line that is too long is for a URL added to the ``linkcheck_ignore``
 variable in the Sphinx configuration (``doc/source/conf.py``) file. Here is an example of how
@@ -150,23 +150,23 @@ Here is what adding these lines looks like:
         "38-comments-and-docstrings",
     ]
 
-If you committed the preceding changes, Sphinx would no longer find any broken links. However, Flake8
+If you committed the preceding changes, Sphinx would no longer find any broken links. However, Ruff
 would throw line length errors for the two lines that define the items for the ``linkcheck_ignore`` variable
 in the Sphinx :file:`config.py` file. Because you cannot modify the length of these lines, you must follow
-each of these URLs (and any comment about it) with a space and then ``# noqa: 501``.
+each of these URLs (and any comment about it) with a space and then ``# noqa: E501``.
 
-You can scroll to the end of these lines to see how they now conclude with ``# noqa: 501``:
+You can scroll to the end of these lines to see how they now conclude with ``# noqa: E501``:
 
 .. code::
 
     # Linkcheck ignore too long lines
 
     linkcheck_ignore = [
-        "https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys GitHub account # noqa: 501
-        "https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys internal GitHub account # noqa: 501
+        "https://myapps.microsoft.com/signin/8f67c59b-83ac-4318-ae96-f0588382ddc0?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys GitHub account # noqa: E501
+        "https://myapps.microsoft.com/signin/42c0fa04-03f2-4407-865e-103af6973dae?tenantId=34c6ce67-15b8-4eff-80e9-52da8be89706", # Join Ansys internal GitHub account # noqa: E501
     ]
 
-When you commit these changes, Flake sees the ``# noqa: 501`` comments at the end of these lines
+When you commit these changes, Ruff sees the ``# noqa: E501`` comments at the end of these lines
 and knows to ignore their long line lengths.
 
 .. _resolve_mismatched_message_strings:

doc/source/links.rst

@@ -82,6 +82,7 @@
 .. _numpy: https://numpy.org/
 .. _pandas: https://pandas.pydata.org/
 .. _pre-commit: https://pre-commit.com/
+.. _Ruff: https://docs.astral.sh/ruff/
 .. _scipy: https://scipy.org/
 .. _tox: https://tox.wiki/en/latest/
 .. _tox_repo: https://github.com/tox-dev/tox