Format only rst files with blackdoc (pyvista#6994)

* Format only rst files with blackdoc

* Auto fix some rst files

* Fix some code blocks

---------

Co-authored-by: Tetsuo Koyama <[email protected]>

Author: beroda

.pre-commit-config.yaml

@@ -10,8 +10,7 @@ repos:
     hooks:
       - id: blackdoc
         args: ["--skip-string-normalization"]
-        files: '\.py$'
-        exclude: pyvista/plotting/charts.py
+        types_or: [rst]
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.3.0

CITATION.rst

@@ -14,7 +14,7 @@ visibility by citing our work.
 
 BibTex:
 
-.. code::
+.. code:: latex
 
     @article{sullivan2019pyvista,
       doi = {10.21105/joss.01450},

CONTRIBUTING.rst

@@ -221,7 +221,7 @@ Python <https://www.python.org/dev/peps/pep-0020/>`_. When in doubt:
 
 .. code:: python
 
-   import this
+    import this
 
 PyVista uses `pre-commit`_ to enforce PEP8 and other styles
 automatically. Please see the `Style Checking section <#style-checking>`_ for
@@ -243,14 +243,14 @@ and partially enforced for Python source files.
 These rules are enforced through the use of `Vale <https://vale.sh/>`_ via our
 GitHub Actions, and you can run Vale locally with:
 
-.. code::
+.. code:: bash
 
    pip install vale
    vale --config doc/.vale.ini doc pyvista examples ./*.rst --glob='!*{_build,AUTHORS.rst}*'
 
 If you are on Linux or macOS, you can run:
 
-.. code::
+.. code:: bash
 
    make docstyle
 
@@ -387,6 +387,7 @@ directive.
     import warnings
     from pyvista.core.errors import PyVistaDeprecationWarning
 
+
     def addition(a, b):
         """Add two numbers.
 
@@ -410,7 +411,7 @@ directive.
         # deprecated 0.37.0, convert to error in 0.40.0, remove 0.41.0
         warnings.warn(
             '`addition` has been deprecated. Use pyvista.add instead',
-            PyVistaDeprecationWarning
+            PyVistaDeprecationWarning,
         )
         add(a, b)
 
@@ -621,15 +622,14 @@ the ``verify_image_cache`` fixture can be utilized:
 
 .. code:: python
 
-
-       def test_add_background_image_not_global(verify_image_cache):
-           verify_image_cache.skip = True  # Turn off caching
-           plotter = pyvista.Plotter()
-           plotter.add_mesh(sphere)
-           plotter.show()
-           # Turn on caching for further plotting
-           verify_image_cache.skip = False
-           ...
+    def test_add_background_image_not_global(verify_image_cache):
+        verify_image_cache.skip = True  # Turn off caching
+        plotter = pyvista.Plotter()
+        plotter.add_mesh(sphere)
+        plotter.show()
+        # Turn on caching for further plotting
+        verify_image_cache.skip = False
+        ...
 
 This ensures that immediately before the plotter is closed, the current
 render window will be verified against the image in CI. If no image
@@ -720,7 +720,7 @@ included in a single ``.py`` file. The test cases are all stored in
 
 The tests can be executed with:
 
-.. code:: python
+.. code:: bash
 
     pytest tests/core/typing
 
@@ -965,11 +965,14 @@ download the dataset in ``pyvista/examples/downloads.py``. This might be as easy
 
 .. code:: python
 
-   def download_my_new_mesh(load=True):
-       """Download my new mesh."""
-       return _download_dataset(_dataset_my_new_mesh, load=load)
+    def download_my_new_mesh(load=True):
+        """Download my new mesh."""
+        return _download_dataset(_dataset_my_new_mesh, load=load)
+
 
-    _dataset_my_new_mesh = _SingleFileDownloadableDatasetLoader('mydata/my_new_mesh.vtk')
+    _dataset_my_new_mesh = _SingleFileDownloadableDatasetLoader(
+        'mydata/my_new_mesh.vtk'
+    )
 
 Note that a separate dataset loading object, ``_dataset_my_new_mesh``, should
 first be defined outside of the function (with module scope), and the new
@@ -1004,21 +1007,21 @@ For example:
 
 .. code:: python
 
-   def download_my_new_mesh(load=True):
-      """Download my new mesh.
+    def download_my_new_mesh(load=True):
+        """Download my new mesh.
 
-      Examples
-      --------
-      >>> from pyvista import examples
-      >>> dataset = examples.download_my_new_mesh()
-      >>> dataset.plot()
+        Examples
+        --------
+        >>> from pyvista import examples
+        >>> dataset = examples.download_my_new_mesh()
+        >>> dataset.plot()
 
-      .. seealso::
+        .. seealso::
 
-         :ref:`My New Mesh Dataset <my_new_mesh_dataset>`
-             See this dataset in the Dataset Gallery for more info.
+           :ref:`My New Mesh Dataset <my_new_mesh_dataset>`
+               See this dataset in the Dataset Gallery for more info.
 
-      """
+        """
 
 .. note::
 

README.rst

@@ -284,7 +284,7 @@ visibility by citing our work.
 
 BibTex:
 
-.. code::
+.. code:: latex
 
     @article{sullivan2019pyvista,
       doi = {10.21105/joss.01450},

doc/source/api/core/pointsets.rst

@@ -221,24 +221,38 @@ initializing.
    >>> import numpy as np
    >>> import pyvista
    >>> from pyvista import CellType
-   >>> cells = np.array([8, 0, 1, 2, 3, 4, 5, 6, 7, 8, 8, 9, 10, 11, 12, 13, 14, 15])
-   >>> cell_type = np.array([CellType.HEXAHEDRON, CellType.HEXAHEDRON], np.int8)
-   >>> cell1 = np.array([[0, 0, 0],
-   ...                   [1, 0, 0],
-   ...                   [1, 1, 0],
-   ...                   [0, 1, 0],
-   ...                   [0, 0, 1],
-   ...                   [1, 0, 1],
-   ...                   [1, 1, 1],
-   ...                   [0, 1, 1]], dtype=np.float32)
-   >>> cell2 = np.array([[0, 0, 2],
-   ...                   [1, 0, 2],
-   ...                   [1, 1, 2],
-   ...                   [0, 1, 2],
-   ...                   [0, 0, 3],
-   ...                   [1, 0, 3],
-   ...                   [1, 1, 3],
-   ...                   [0, 1, 3]], dtype=np.float32)
+   >>> cells = np.array(
+   ...     [8, 0, 1, 2, 3, 4, 5, 6, 7, 8, 8, 9, 10, 11, 12, 13, 14, 15]
+   ... )
+   >>> cell_type = np.array(
+   ...     [CellType.HEXAHEDRON, CellType.HEXAHEDRON], np.int8
+   ... )
+   >>> cell1 = np.array(
+   ...     [
+   ...         [0, 0, 0],
+   ...         [1, 0, 0],
+   ...         [1, 1, 0],
+   ...         [0, 1, 0],
+   ...         [0, 0, 1],
+   ...         [1, 0, 1],
+   ...         [1, 1, 1],
+   ...         [0, 1, 1],
+   ...     ],
+   ...     dtype=np.float32,
+   ... )
+   >>> cell2 = np.array(
+   ...     [
+   ...         [0, 0, 2],
+   ...         [1, 0, 2],
+   ...         [1, 1, 2],
+   ...         [0, 1, 2],
+   ...         [0, 0, 3],
+   ...         [1, 0, 3],
+   ...         [1, 1, 3],
+   ...         [0, 1, 3],
+   ...     ],
+   ...     dtype=np.float32,
+   ... )
    >>> points = np.vstack((cell1, cell2))
    >>> grid = pyvista.UnstructuredGrid(cells, cell_type, points)
    >>> grid

doc/source/api/plotting/plotting.rst

@@ -127,9 +127,16 @@ values change through time:
 
 
     plotter = pvqt.BackgroundPlotter()
-    plotter.add_mesh(globe, lighting=False, show_edges=True, texture=texture, scalars='scalars')
+    plotter.add_mesh(
+        globe,
+        lighting=False,
+        show_edges=True,
+        texture=texture,
+        scalars='scalars',
+    )
     plotter.view_isometric()
 
+
     # shrink globe in the background
     def shrink():
         for i in range(50):
@@ -138,6 +145,7 @@ values change through time:
             globe.point_data['scalars'] = np.random.rand(globe.n_points)
             time.sleep(0.5)
 
+
     thread = Thread(target=shrink)
     thread.start()
 

doc/source/api/utilities/utilities.rst

@@ -131,28 +131,21 @@ PyVista Version Information
 The PyVista library provides a way of getting the version installed in your
 environment.
 
-.. code:: python
-
-   Output the version of PyVista.
-
-   >>> import pyvista
-   >>> pyvista.version_info
-   (0, 44, 0)
+>>> # Output the version of PyVista.
+>>> import pyvista
+>>> pyvista.version_info
+(0, 44, 0)
 
 VTK Version Information
 ~~~~~~~~~~~~~~~~~~~~~~~
 The PyVista library is heavily dependent on VTK and provides an easy
 way of getting the version of VTK in your environment.
 
-.. code:: python
-
-   Output the version of VTK.
-
-   >>> import pyvista
-   >>> pyvista.vtk_version_info
-   VTKVersionInfo(major=9, minor=1, micro=0)
-
-   Get the major version of VTK
+>>> # Output the version of VTK.
+>>> import pyvista
+>>> pyvista.vtk_version_info
+VTKVersionInfo(major=9, minor=1, micro=0)
 
-   >>> pyvista.vtk_version_info.major
-   9
+>>> # Get the major version of VTK
+>>> pyvista.vtk_version_info.major
+9

doc/source/extras/plot_directive.rst

@@ -8,11 +8,11 @@ You can generate static and interactive scenes of pyvista plots using the
 
 .. code:: python
 
-   extensions = [
-       "pyvista.ext.plot_directive",
-       "pyvista.ext.viewer_directive",
-       "sphinx_design",
-   ]
+    extensions = [
+        "pyvista.ext.plot_directive",
+        "pyvista.ext.viewer_directive",
+        "sphinx_design",
+    ]
 
 You can then issue the plotting directive within your sphinx
 documentation files::

doc/source/getting-started/index.rst

@@ -106,9 +106,11 @@ through a range of examples and tutorials.
    :include-source: False
    :context:
 
-   >>> bunny_cpos = [( 0.14826, 0.275729,  0.4215911),
-   ...               (-0.01684, 0.110154, -0.0015369),
-   ...               (-0.15446, 0.939031, -0.3071841)]
+   >>> bunny_cpos = [
+   ...     (0.14826, 0.275729, 0.4215911),
+   ...     (-0.01684, 0.110154, -0.0015369),
+   ...     (-0.15446, 0.939031, -0.3071841),
+   ... ]
 
 
 .. grid:: 2
@@ -123,9 +125,10 @@ through a range of examples and tutorials.
 
       .. code:: python
 
-         import pyvista
-         mesh = pyvista.read('bunny.stl')
-         mesh.plot()
+          import pyvista
+
+          mesh = pyvista.read('bunny.stl')
+          mesh.plot()
 
       .. pyvista-plot::
          :include-source: False

doc/source/getting-started/installation.rst

@@ -318,6 +318,7 @@ should be displayed in JupyterLab.
 .. code-block:: python
 
     import pyvista
+
     pl = pyvista.Plotter(shape=(1, 2))
     actor = pl.add_mesh(pyvista.Cube())
     pl.subplot(0, 1)
@@ -335,6 +336,7 @@ In your ``conf.py``, add the following:
 .. code-block:: python
 
     import pyvista
+
     # necessary when building the sphinx gallery
     pyvista.BUILDING_GALLERY = True
     pyvista.OFF_SCREEN = True
@@ -344,15 +346,15 @@ In your ``conf.py``, add the following:
     pyvista.global_theme.window_size = np.array([1024, 768]) * 2
 
     extensions = [
-        ...
+        ...,
         "sphinx_gallery.gen_gallery",
     ]
 
     # Add the PyVista image scraper to SG
     sphinx_gallery_conf = {
-        ...
-        "image_scrapers": ('pyvista', ..., ),
-        ...
+        ...: ...,
+        "image_scrapers": ('pyvista', ...),
+        ...: ...,
     }
 
 We also have a Sphinx-Gallery scraper for embedding dynamic 3D scenes
@@ -375,14 +377,14 @@ the string ``'pyvista'`` above and by registering the
     pyvista.global_theme.window_size = np.array([1024, 768]) * 2
 
     extensions = [
-        ...
+        ...,
         "sphinx_gallery.gen_gallery",
         "pyvista.ext.viewer_directive",
     ]
 
     # Add the PyVista image scraper to SG
     sphinx_gallery_conf = {
-        ...
-        "image_scrapers": (DynamicScraper(), ..., ),
-        ...
+        ...: ...,
+        "image_scrapers": (DynamicScraper(), ...),
+        ...: ...,
     }

doc/source/getting-started/why.rst

@@ -41,9 +41,11 @@ requires a few lines of code.
    :include-source: False
    :context:
 
-   >>> bunny_cpos = [( 0.14826, 0.275729,  0.4215911),
-   ...               (-0.01684, 0.110154, -0.0015369),
-   ...               (-0.15446, 0.939031, -0.3071841)]
+   >>> bunny_cpos = [
+   ...     (0.14826, 0.275729, 0.4215911),
+   ...     (-0.01684, 0.110154, -0.0015369),
+   ...     (-0.15446, 0.939031, -0.3071841),
+   ... ]
 
 +----------------------------------------------------+-------------------------------------+
 | Read and plot STL file using `vtk`_                | Read an STL file using PyVista      |