Edit doc overall based on PyAnsys doc style guidelines

.github/workflows/ci.yml

@@ -46,6 +46,24 @@ jobs:
         run: |
           pre-commit run --all-files --show-diff-on-failure
 
+  docs-style:
+    name: Documentation Style Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Running Vale
+        uses: errata-ai/vale-action@reviewdog
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        with:
+          files: doc
+          reporter: github-pr-check
+          level: error
+          filter_mode: nofilter
+          fail_on_error: true
+          vale_flags: "--config=doc/.vale.ini"
+
   test-import:
     name: Smoke Tests
     runs-on: ${{ matrix.os }}
@@ -88,6 +106,7 @@ jobs:
 
   docs_build:
     name: Build Documentation
+    needs: [docs-style]
     runs-on: [self-hosted, pyfluent]
     strategy:
       matrix:

CONTRIBUTING.md

@@ -1,13 +1,11 @@
 # Contributing
 
-We absolutely welcome any code contributions and we hope that this guide will
-facilitate an understanding of the PyFluent code repository. It is important to
-note that while the PyFluent software package is maintained by ANSYS and any
-submissions will be reviewed thoroughly before merging, we still seek to foster
+We welcome any code contributions and hope that this guide facilitates
+an understanding of the PyFluent code repository. It is important to
+note that while the PyFluent software package is maintained by Ansys and any
+submissions are reviewed thoroughly before merging, we still seek to foster
 a community that can support user questions and develop new features to make
-this software a useful tool for all users.  As such, we welcome and encourage
+this software a useful tool for all users. As such, we welcome and encourage
 any questions or submissions to this repository.
 
-Please reference
-[Contributing](https://fluentdocs.pyansys.com/contributing.html) for the full
-documentation regarding contributing to the PyFluent project.
+For more information on contributing to PyFluent, see [Contributing](https://fluentdocs.pyansys.com/contributing.html).

README.rst

@@ -24,22 +24,22 @@ PyFluent
 
 Overview
 --------
-The PyFluent project provides Pythonic access to Ansys Fluent.  The package
-provides features to enable seamless use of Fluent within the Python ecosystem
-as well as broad access to Fluent features including:
+PyFluent provides Pythonic access to Ansys Fluent. Its features enable the seamless use of
+Fluent within the Python ecosystem and broad access to native Fluent features, including the
+ability to:
 
-- Ability to launch Fluent using a local Ansys installation
-- Ability to use Fluent TUI commands for both meshing and solver features
-- Ability to use Fluent's in-built post processing capabilities
+- Launch Fluent using a local Ansys installation
+- Use Fluent's TUI (text user interface) commands for both meshing and solver features
+- Use Fluent's built-in postprocessing capabilities
 
-Documentation and Issues
+Documentation and issues
 ------------------------
-Please see the latest release `documentation <https://fluentdocs.pyansys.com>`_
-page for more details.
+For comprehesive information on PyFluent, see the latest release
+`documentation <https://fluentdocs.pyansys.com>`_.
 
-Please feel free to post issues and other questions at `PyFluent Issues
-<https://github.com/pyansys/pyfluent/issues>`_.  This is the best place
-to post questions and code.
+On the `PyFluent Issues <https://github.com/pyansys/pyfluent/issues>`_, you can create
+issues to submit questions, report bugs, and request new features. To reach
+the project support team, email `pyansys.support@ansys.com <pyansys.support@ansys.com>`_.
 
 Installation
 ------------
@@ -53,14 +53,14 @@ Install the latest release from `PyPI
 
    pip install ansys-fluent-core
 
-Alternatively, install the latest from `PyFluent GitHub
-<https://github.com/pyansys/pyfluent>`_ via:
+Alternatively, install the latest version from the `PyFluent GitHub
+repository <https://github.com/pyansys/pyfluent>`_ with:
 
 .. code:: console
 
    pip install git+https://github.com/pyansys/pyfluent.git
 
-If you plan on doing local "development" of PyFluent with Git, then install
+If you plan on doing local "development" of PyFluent with Git, install
 with:
 
 .. code:: console
@@ -69,14 +69,14 @@ with:
    cd pyfluent
    pip install pip -U
    pip install -e .
-   python codegen/allapigen.py  # Generates the API files, requires Fluent
+   python codegen/allapigen.py  # Generates the API files
 
 Dependencies
 ------------
-You will need a locally installed licensed copy of ANSYS to run Fluent, with the
-first supported version being Ansys 2022 R2.
+You must have a locally-installed, licensed copy of Ansys to run Fluent. The
+first supported version is 2022 R2.
 
-Getting Started
+Getting started
 ---------------
 
 Launching Fluent
@@ -89,9 +89,10 @@ You can launch Fluent from Python using the ``launch_fluent`` function:
   session = pyfluent.launch_fluent()
   session.check_health()
 
-To use a non-default install location set the ``PYFLUENT_FLUENT_ROOT``
-environment variable to the ``<version>/fluent`` directory where ``<version>``
-is the Ansys release version you would like to use (eg: v222).
+To use a non-default installation location, set the ``PYFLUENT_FLUENT_ROOT``
+environment variable to the ``<version>/fluent`` directory, where ``<version>``
+is the Ansys release version that you would like to use. For example, ``v222``
+uses version 2022 R2.
 
 Basic Usage
 ~~~~~~~~~~~
@@ -104,22 +105,22 @@ You can run Fluent TUI commands using the ``session.tui`` interface:
   session.solver.tui.solve.initialize.initialize_flow()
   session.solver.tui.solve.dual_time_iterate(2, 3)
 
-In addition to all TUI commands being available there are the
+In addition to all TUI commands being available, there are the
 `PyFluent Parametric <https://fluentparametric.docs.pyansys.com/>`_ and
 `PyFluent Visualization <https://fluentvisualization.docs.pyansys.com/>`_ packages.
-The PyFluent Parametric package provides access to Fluent's parametric workflows and
-the PyFluent Visualization package provides post-processing and visualization
-capabilities using `pyvista <https://docs.pyvista.org/>`_ and
-`matplotlib <https://matplotlib.org/>`_.
 
-License and Acknowledgments
+- The PyFluent Parametric package provides access to Fluent's parametric workflows.
+- The PyFluent Visualization package provides postprocessing and visualization
+  capabilities using `pyvista <https://docs.pyvista.org/>`_ and `matplotlib <https://matplotlib.org/>`_.
+
+License and acknowledgments
 ---------------------------
 ``PyFluent`` is licensed under the MIT license.
 
 This module, ``ansys-fluent`` makes no commercial claim over Ansys whatsoever.
-This tool extends the functionality of ``Fluent`` by adding a Python interface
-to the Fluent without changing the core behavior or license of the original
-software.  The use of the interactive Fluent control of ``PyFluent`` requires a
-legally licensed local copy of Ansys.
-
-To get a copy of Ansys, please visit `Ansys <https://www.ansys.com/>`_.
+PyFluent extends the functionality of Fluent by adding a Python interface
+to Fluent without changing the core behavior or license of the original
+software. The use of the interactive control of ``PyFluent`` requires a
+legally licensed local copy of Fluent. For more information about Fluent,
+visit the `Fluent page <https://www.ansys.com/products/fluids/ansys-fluent>`_ 
+on the Ansys website.

doc/.vale.ini

@@ -0,0 +1,32 @@
+# Core settings
+# =============
+
+# Location of our `styles`
+StylesPath = "styles"
+
+# The options are `suggestion`, `warning`, or `error` (defaults to “warning”).
+MinAlertLevel = warning
+
+# By default, `code` and `tt` are ignored.
+IgnoredScopes = code, tt
+
+# By default, `script`, `style`, `pre`, and `figure` are ignored.
+SkippedScopes = script, style, pre, figure
+
+# WordTemplate specifies what Vale will consider to be an individual word.
+WordTemplate = \b(?:%s)\b
+
+# List of Packages to be used for our guidelines
+Packages = Google
+
+# Define the Ansys vocabulary
+Vocab = ANSYS
+
+[*.{md,rst}]
+
+# Apply the following styles
+BasedOnStyles = Vale, Google
+
+# Removing Google-specific rule - Not applicable under some circumstances
+Google.WordList = NO
+Google.Colons = NO

doc/source/api/core/meshing/index.rst

@@ -2,10 +2,10 @@
 
 Meshing
 =======
-This module allows you to use Fluent meshing capabilities from Python.  Both
-the meshing workflows and meshing TUI commands are available.
+This module allows you to use Fluent meshing capabilities from Python. Both
+of the meshing workflows and the meshing TUI commands are available.
 
-Workflow Example
+Workflow example
 ----------------
 
 .. code:: python
@@ -19,11 +19,11 @@ Workflow Example
     session.meshing.tui.mesh.check_mesh()
     exit()
 
-Existing Fluent meshing workflows journals can also be converted to the
-session based PyFluent scripts with some manual modifications.
-For example:
+You can manually convert existing Fluent meshing workflow
+journals to session-based PyFluent scripts. Examples follow of a Fluent journal
+and the equivalent PyFluent script.
 
-Fluent Journal:
+**Fluent journal**
 
 .. code-block::
 
@@ -49,7 +49,7 @@ Fluent Journal:
   (%py-exec "workflow.TaskObject['Generate the Volume Mesh'].Arguments.setState({r'VolumeFill': r'poly-hexcore',r'VolumeFillControls': {r'HexMaxCellLength': 0.3,},})")
   (%py-exec "workflow.TaskObject['Generate the Volume Mesh'].Execute()")
 
-Equivalent PyFluent Journal:
+**PyFluent script**
 
 .. code:: python
 
@@ -97,7 +97,7 @@ Equivalent PyFluent Journal:
   }
   session.meshing.workflow.TaskObject["Generate the Volume Mesh"].Execute()
 
-TUI Commands Example
+TUI commands example
 --------------------
 
 .. code:: python

doc/source/api/core/solver/events.rst

@@ -4,16 +4,22 @@ EventsManager
 =============
 
 An instance of ``EventsManager`` exists as an active ``events_manager`` property in each
-solution-mode session object. It allows to register client callback with server side events.
-Whenever event occurs, the registered callback is triggered with session id and event info 
-passed as arguments to callback. It is useful in solution monitoring and updating graphics 
-during run time.
+solution-mode session object. You can register client callbacks with the EventsManager.
+The EventsManager calls each callback whenever a server-side event occurs, passing session ID
+and event information arguments to the callback. The EventsManager is useful for solution
+monitoring and updating graphics during runtime.
 
 Supported events are:
-``CalculationsEndedEvent, CalculationsStartedEvent, CaseReadEvent, DataReadEvent, 
-InitializedEvent, IterationEndedEvent, ProgressEvent, TimestepEndedEvent``
 
-Following code will trigger callback at end of every iteration.
+- ``CalculationsEndedEvent``
+- ``CalculationsStartedEvent``
+- ``CaseReadEvent, DataReadEvent``
+- ``InitializedEvent``
+- ``IterationEndedEvent``
+- ``ProgressEvent``
+- ``TimestepEndedEvent``
+
+The following code triggers a callback at the end of every iteration.
 
 .. code-block:: python