Implementing pre-commit.ci and blacken-docs hook (#228)

* Pre-commit autoupdate

* Updating pipeline

* Adding pre-commit blacken-docs hook

* Typo in workflow

* Blacken docs

* Bugged snippet

* Add disclaimer

* Avoid concurrent workflows

* Adding empty line (by @germa89)

Author: RobPasMue

.github/workflows/ci-build.yml

@@ -12,41 +12,35 @@ env:
   MAIN_PYTHON_VERSION: '3.10'
   CNAME: 'dev.docs.pyansys.com'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: write
   pull-requests: write
 
 jobs:
 
-  code-style:
-    name: "Check code style"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "Check code style"
-        uses: pyansys/actions/code-style@v1
-        with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-          use-python-cache: false
-
   doc-style:
     name: "Check documentation style"
     runs-on: ubuntu-latest
     steps:
       - name: "Check documentation style"
-        uses: pyansys/actions/doc-style@v1
+        uses: pyansys/actions/doc-style@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
   doc-build:
     name: "Build project documentation"
-    needs: [code-style, doc-style]
+    needs: doc-style
     runs-on: ubuntu-latest
     steps:
       - name: "Install mermaid-cli"
         run: npm install -g @mermaid-js/mermaid-cli
 
       - name: "Build project documentation"
-        uses: pyansys/actions/doc-build@v1
+        uses: pyansys/actions/doc-build@v2
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
           use-python-cache: false
@@ -61,7 +55,7 @@ jobs:
     needs: doc-build
     steps:
       - name: "Deploy development documentation"
-        uses: pyansys/actions/doc-deploy-dev@v1
+        uses: pyansys/actions/doc-deploy-dev@v2
         with:
           cname: ${{ env.CNAME }}
           token: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -2,13 +2,19 @@ repos:
 
 
 - repo: https://github.com/psf/black
-  rev: 22.3.0
+  rev: 22.12.0  # IF VERSION CHANGES --> MODIFY "blacken-docs" MANUALLY AS WELL!!
   hooks:
   - id: black
     args: ["doc/source/conf.py"]
 
+- repo: https://github.com/adamchainz/blacken-docs
+  rev: v1.12.1
+  hooks:
+  - id: blacken-docs
+    additional_dependencies: [black==22.12.0]
+
 - repo: https://github.com/pycqa/isort
-  rev: 5.10.1
+  rev: 5.11.4
   hooks:
   - id: isort
     args: [
@@ -18,24 +24,24 @@ repos:
     ]
 
 - repo: https://github.com/PyCQA/flake8
-  rev: 5.0.4
+  rev: 6.0.0
   hooks:
   - id: flake8
 
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.1.0
+  rev: v2.2.2
   hooks:
   - id: codespell
     args: [--ignore-words=ignore_words.txt, -S \*.pyc\,\*.xml\,\*.txt\,\*.gif\,\*.png\,\*.jpg\,\*.js\,\*.html\,\*.doctree\,\*.ttf\,\*.woff\,\*.woff2\,\*.eot\,\*.mp4\,\*.inv\,\*.pickle\,\*.ipynb\,flycheck\*\,./.git/\*\,./.hypothesis/\*\,\*.yml\,./doc/build/\*\,./doc/images/\*\,./dist/\*\,\*~\,.hypothesis\*\,./doc/source/examples/\*\,\*cover\,\*.dat\,\*.mac]
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.1.0
+  rev: v4.4.0
   hooks:
   - id: check-merge-conflict
   - id: debug-statements
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.16.0
+  rev: 0.19.2
   hooks:
     - id: check-github-workflows
       name: "Check GitHub workflows"

doc/source/abstractions/data-transfer.rst

@@ -12,10 +12,10 @@ For example, consider a simple mesh in MAPDL:
 
 .. code:: python
 
-   >>> mapdl.prep7()
-   >>> mapdl.block(0, 1, 0, 1, 0, 1)
-   >>> mapdl.et(1, 186)
-   >>> mapdl.vmesh('ALL')
+   mapdl.prep7()
+   mapdl.block(0, 1, 0, 1, 0, 1)
+   mapdl.et(1, 186)
+   mapdl.vmesh("ALL")
 
 At this point, there are only two ways within MAPDL to access the nodes and
 connectivity of the mesh, You can either print it using the ``NLIST``
@@ -29,13 +29,14 @@ methods are remarkably inefficient, requiring:
 
 This example prints node coordinates using the ``NLIST`` command:
 
-.. code:: python
+.. code:: pycon
 
    >>> print(mapdl.nlist())
-       NODE        X             Y             Z
-        1   0.0000        1.0000        0.0000
-        2   0.0000        0.0000        0.0000
-        3   0.0000       0.75000        0.0000
+
+   NODE        X             Y             Z
+    1   0.0000        1.0000        0.0000
+    2   0.0000        0.0000        0.0000
+    3   0.0000       0.75000        0.0000
 
 It's more efficient to transfer the node array as either a
 series of repeated ``Node`` messages or, better yet, to serialize 
@@ -54,7 +55,7 @@ the nodes of the mesh are accessible as the ``nodes`` attribute within
 the ``mesh`` attribute, which provides an encapsulation of the mesh
 within the MAPDL database.
 
-.. code:: python
+.. code:: pycon
 
    >>> mapdl.mesh.nodes
    array([[0.  , 1.  , 0.  ],

doc/source/abstractions/service.rst

@@ -63,11 +63,12 @@ way to do this is to include a function to launch the service.
 This example includes ``launch_mapdl``, which brokers a connection via the 
 ``Mapdl`` class:
 
-.. code:: python
+.. code:: pycon
 
    >>> from ansys.mapdl.core import Mapdl
-   >>> mapdl = Mapdl(ip=<IP Address>, port=<Port>)
+   >>> mapdl = Mapdl(ip=whatever_ip, port=whatever_port)
    >>> print(mapdl)
+
    Product:             Ansys Mechanical Enterprise
    MAPDL Version:       21.2
    ansys.mapdl Version: 0.59.dev0

doc/source/coding-style/deprecation.rst

@@ -24,7 +24,8 @@ a minor release or two.
 
     import warnings
 
-    class FieldAnalysis2D():
+
+    class FieldAnalysis2D:
         """Class docstring"""
 
         def assignmaterial(self, obj, mat):
@@ -37,12 +38,16 @@ a minor release or two.
             # one of the following:
 
             # raise a DeprecationWarning. User won't have to change anything
-            warnings.warn('`assignmaterial` is deprecated. Use `assign_material` instead.',
-                          DeprecationWarning)
+            warnings.warn(
+                "`assignmaterial` is deprecated. Use `assign_material` instead.",
+                DeprecationWarning,
+            )
             self.assign_material(obj, mat)
 
             # or raise an AttributeError (could also make a custom DeprecationError)
-            raise AttributeError('`assignmaterial` is deprecated. Use `assign_material` instead.')
+            raise AttributeError(
+                "`assignmaterial` is deprecated. Use `assign_material` instead."
+            )
 
         def assign_material(self, obj, mat):
             """Assign a material to one or more objects.
@@ -62,17 +67,17 @@ method. Simply raise an ``AttributeError`` as part of the class or raise an ``Ex
             This function has been deprecated.
 
         """
-        raise Exception('`my_function` has been deprecated')
+        raise Exception("`my_function` has been deprecated")
 
-Because there is no built-in depreciation error within Python, an alternate
+Because there is no built-in deprecation error within Python, an alternate
 approach is to create a custom ``DeprecationError``.
 
 .. code:: python
 
     class DeprecationError(RuntimeError):
-        """Used for depreciated methods and functions."""
+        """Used for deprecated methods and functions."""
 
-        def __init__(self, message='This feature has been depreciated.'):
+        def __init__(self, message="This feature has been deprecated."):
             """Empty init."""
             RuntimeError.__init__(self, message)
 

doc/source/coding-style/pep8.rst

@@ -136,7 +136,6 @@ more readable and reliable.
     .. tab-item:: Use
     
         .. code-block:: python
-            
            from ansys.mapdl.core.plotting import general_plotter
 
     .. tab-item:: Avoid
@@ -370,11 +369,11 @@ Instead of:
            else:
 
                if x > y:
-        
+
                    ...
 
                else:
-        
+
                    ...
 
            if x > 0 and x < 10:
@@ -407,10 +406,14 @@ this line is difficult to follow:
 
     .. tab-item:: Avoid
 
-        .. code:: python
+        .. code-block:: python
+
+            # fmt: off
 
             employee_hours = [schedule.earliest_hour for employee in self.public_employees for schedule in employee.schedules]
 
+            # fmt: on
+
 Alternatively, instead of writing a list comprehension, you can use a
 classic loop.
 
@@ -794,12 +797,13 @@ example, to extract all consonants in a sentence:
                 """Return ``True`` when a letter is a consonant."""
                 vowels = 'aeiou'
                 return letter.isalpha() and letter.lower() not in vowels
-       
+        
         .. code-block:: pycon
-    
+            
             >>> sentence = "This is a sample sentence."
             >>> consonants = [letter for letter in sentence if is_consonant(letter)]
             >>> print(f"{consonants = }")
+
             consonants = ['T', 'h', 's', 's', 's', 'm', 'p', 'l', 's', 'n', 't', 'n', 'c']
 
     .. tab-item:: Avoid
@@ -816,6 +820,7 @@ example, to extract all consonants in a sentence:
         .. code-block:: pycon 
         
             >>> print(f"{consonants = }")
+
             consonants = ['T', 'h', 's', 's', 's', 'm', 'p', 'l', 's', 'n', 't', 'n', 'c']
 
 The second approach is more readable and better documented. Additionally,

doc/source/conf.py

@@ -71,7 +71,7 @@
     "examples_dirs": ["../../examples"],  # ["../../examples/"],
     # path where to save gallery generated examples
     "gallery_dirs": ["examples"],
-    # Patter to search for example files
+    # Pattern to search for example files
     "filename_pattern": r"\.py",
     # Remove the "Download all examples" button from the top level gallery
     "download_all_examples": False,

doc/source/doc-style/docstrings.rst

@@ -247,14 +247,16 @@ Instead, you should render type hints as part of each parameter's description. T
 accomplish this, you must combine the ``sphinx.ext.autodoc.typehints``, ``sphinx.ext.napoleon``,
 and ``numpydoc`` extensions in the ``conf.py`` file:
 
+
+
 .. code:: python
 
    extensions = [
-       ...
+       ...,
        "sphinx.ext.autodoc.typehints",
        "sphinx.ext.napoleon",
        "numpydoc",
-       ...
+       ...,
    ]
    autodoc_typehints = "description"
 

doc/source/how-to/compatibility.rst

@@ -49,7 +49,7 @@ decorator is used in `ansys/mapdl/core/check_version.py`_ and
 
 .. code:: python
 
-    class Client():
+    class Client:
         def __init__(self):
             """Connect to a fake server."""
             self._server = FakeServer()

doc/source/how-to/documenting.rst

@@ -276,7 +276,7 @@ To describe 'why' and 'how' you use a class within :ref:`RST files`, use the
             .. code-block:: pycon
 
                >>> from my_module import MyClass
-               >>> my_obj = MyClass(parm1='apple', parm2='orange')
+               >>> my_obj = MyClass(parm1="apple", parm2="orange")
                >>> my_obj.parm1
                'apple'
 
@@ -288,7 +288,7 @@ To describe 'why' and 'how' you use a class within :ref:`RST files`, use the
         .. code-block:: pycon
 
            >>> from my_module import MyClass
-           >>> my_obj = MyClass(parm1='apple', parm2='orange')
+           >>> my_obj = MyClass(parm1="apple", parm2="orange")
            >>> my_obj.parm1
            'apple'
 

doc/source/how-to/grpc-api-packages.rst

@@ -62,7 +62,7 @@ To use this, include this tool in the ``pyproject.toml`` file as a build depende
 
 Then generate a Python wheel containing the autogenerated Python source with:
 
-.. code-block:: python
+.. code-block:: bash
 
     pip install -U pip
     pip install build