Merge pull request #78 from NREL/typos_doc

Typos doc

.github/workflows/build_docs.yml

@@ -0,0 +1,40 @@
+name: BiRD-build-documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs_pages.yml'
+  pull_request:
+     branches: [main]
+     paths:
+      - 'docs/**'
+      - '.github/workflows/docs_pages.yml'
+
+jobs:
+
+  build_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx_rtd_theme
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+

.github/workflows/docs_pages.yml → .github/workflows/deploy_docs.yml

@@ -1,4 +1,4 @@
-name: BiRD-documentation
+name: BiRD-deploy-documentation
 
 on:
   push:
@@ -11,9 +11,6 @@ jobs:
 
   build_docs:
     runs-on: ubuntu-latest
-    env:
-      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -34,6 +31,12 @@ jobs:
           cd docs
           make html
 
+  deploy_docs:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
       - name: deploy
         uses: peaceiris/actions-gh-pages@v4
         with:

docs/source/contribute.rst

@@ -6,17 +6,15 @@ We welcome pull requests from anybody!
 Formatting
 ------------
 
-Code formatting and import sorting are done automatically with ``black`` and ``isort``.
+Code formatting, import sorting, and spell checks are done automatically with ``black``, ``isort`` and ``codespell``.
 
 You can automatically enforce the formatting guidelines with
 
 .. code-block:: console
 
-   pip install black isort
+   pip install black isort codespell
    bash fixFormat.sh
 
-Spelling is checked but not automatically fixed using ``codespell``
-
 
 Test
 ------------

docs/source/index.rst

@@ -1,17 +1,18 @@
 Bio Reactor Design (BiRD)
 ===================================
 
-`BiRD` is a toolbox aimed a facilitating the numerical simulation of bioreactors with OpenFOAM.
-The purpose of `BiRD` is 
+`BiRD` is a toolbox for computational fluid dynamics (CFD) simulations of bioreactors with OpenFOAM.
 
-1. to ensure reproducibility of numerical simulations of bioreactors.
-2. to create a suite of test cases that can be used to test different reactor configurations.
-3. to facilitate validation of multiphase flow models against several experimental campaigns.
-4. to facilitate optimization (geometry and operating conditions) of bioreactors. 
+The objective of `BiRD` is to
+
+1. ensure reproducibility of numerical simulations of bioreactors.
+2. create a centralized suite of test cases for different reactor configurations.
+3. facilitate validation of multiphase flow models against several experimental campaigns.
+4. facilitate optimization (geometry and operating conditions) of bioreactors. 
 
 It contains a python module ``bird`` that can be used to generate input files that may be read by OpenFOAM to generate meshes and cases. It can also be used to post process the output of OpenFOAM simulations.
 
-We also provide a solver ``birdmultiphaseEulerFoam`` that contains custom models added to the base OpenFOAM-v9. 
+We provide a solver ``birdmultiphaseEulerFoam`` that contains custom models added to the base OpenFOAM-v9. 
 
 
 .. note::

docs/source/meshing.rst

@@ -16,7 +16,7 @@ Generate a ``blockMeshDict`` with
 
    python applications/write_stirred_tank_mesh.py -i $inp -o $out
 
-Then activate openFoam environment and mesh with
+Then activate openFOAM environment and mesh with
 
 .. code-block:: console
 
@@ -58,7 +58,7 @@ Generates ``system/blockMeshDict``
 
    python applications/write_block_cyl_mesh.py -i $mesh_temp/input.json -t $mesh_temp/topology.json -o $caseFolder/system
 
-Then activate openFoam environment and mesh with
+Then, activate the openFOAM environment and construct the mesh with
 
 .. code-block:: console
 
@@ -68,7 +68,7 @@ Then activate openFoam environment and mesh with
    transformPoints "rotate=((0 0 1) (0 1 0))"
    cd $root
 
-Visualize mesh in Paraview
+Visualize the mesh in Paraview
 
 .. _fig:sidesparger:
 
@@ -82,15 +82,15 @@ Visualize mesh in Paraview
 How to change the dimensions or mesh refinement?
 ^^^^^^^^^^^^^^^
 
-All dimensions and mesh are controlled by the input file ``input.json``.
+The geometry and the mesh size are controlled by the input file ``input.json``.
 The input file can also be in ``.yaml`` format. The parser will decide the file format based on its extension.
 See ``bird/meshing/block_cyl_mesh_templates/baseColumn/`` for an example of ``.yaml``
 
 How to change the arrangement of concentric cylinders?
 ^^^^^^^^^^^^^^^
 
-The block topology is controlled by the ``topology.json``
-We recomment always working with a schematic. Here is the schematic for this case
+The block topology is controlled by ``topology.json``
+We recommend always working with a schematic as shown below
 
 .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematic.png
      :width: 50%
@@ -102,7 +102,7 @@ We recomment always working with a schematic. Here is the schematic for this cas
 
 The purple blocks are walls (not meshed) and the white blocks are fluid blocks (meshed). The symmetry axis is indicated as a dashed line
 
-In the ``topology.json``, the purple blocks are defined as
+In ``topology.json``, the purple blocks are defined as
 
 .. code-block:: json
 
@@ -124,7 +124,7 @@ How to change boundaries?
 
 Boundaries are defined with three types, ``top``, ``bottom`` and ``lateral``
 
-In the case of sparger walls shown below with the red lines
+For example, if one wants to create a boundary called ``wall_sparger``, shown below as the red lines
 
 .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerWalls.png
      :width: 50%
@@ -134,7 +134,7 @@ In the case of sparger walls shown below with the red lines
      :alt: Wall side sparger schematic
 
 
-the boundary is defined in the ``topology.json`` as
+one can define the boundary as follows in ``topology.json``
 
 .. code-block:: json
 
@@ -146,7 +146,7 @@ the boundary is defined in the ``topology.json`` as
                               {"type": "top", "Rmin": 2, "Rmax": 2, "Lmin": 1, "Lmax": 2}
                             ],
 
-For the side sparger, the inlet is shown below with the red line
+For lateral boundaries (called ``inlet`` in this example), and shown below as the red line
 
 .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png
      :width: 50%
@@ -155,7 +155,7 @@ For the side sparger, the inlet is shown below with the red line
      :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png
      :alt: Inlet side sparger schematic
 
-the boundary is defined in the ``topology.json`` as
+one can define the boundary as follows in ``topology.json``
 
 .. code-block:: json
 
@@ -186,15 +186,15 @@ Generates ``system/blockMeshDict``
 
    python applications/write_block_rect_mesh.py -i $mesh_temp/input.json -o $caseFolder/system
 
-Then activate openFoam environment and mesh with
+Then, activate openFOAM environment and construct the mesh with
 
 .. code-block:: console
 
    cd $caseFolder
    blockMesh
    cd $root
 
-Visualize mesh in Paraview
+Visualize the mesh in Paraview
 
 .. _fig:loop_reactor:
 
@@ -220,7 +220,7 @@ The geometry of the block cylindrical mesh is defined within a 3D domain (X,Y,Z)
      :alt: Loop reactor schematic
 
 
-The corners are defined in the ``input.json``
+The corners are defined in ``input.json``
 
 .. code-block:: json
 

docs/source/preprocess.rst

@@ -7,14 +7,14 @@ Preprocess
 Generate STL patch mesh
 ------------
 
-Boundaries may be specified with ``surfaceToPatch`` utility in OpenFOAM, based on STL files that can be generated with
+Boundaries may be specified with the ``surfaceToPatch`` utility in OpenFOAM, based on STL files that can be generated with
 
 .. code-block:: console
 
    python applications/write_stl_patch.py -v
 
 
-The verbose flag (``-v``) generates a plot of the stl mesh
+The verbose flag (``-v``) generates a plot of the stl mesh (as shown below)
 
 .. _fig:stl_patch:
 
@@ -28,7 +28,7 @@ The verbose flag (``-v``) generates a plot of the stl mesh
 How to change the set of shapes in the boundary patch?
 ^^^^^^^^^^^^^^^
 
-Edit the json files read when generating the mesh. In the case ``tutorial_cases/loop_reactor_mixing`` the boundary condition ``inlets`` consists of 3 discs
+Edit the json files that are read when generating the mesh. In the case ``tutorial_cases/loop_reactor_mixing``, the boundary condition ``inlets`` consists of 3 discs
 
 .. code-block:: json
 

docs/source/quickstart.rst

@@ -47,8 +47,8 @@ Installation of BiRD OpenFOAM solver (for developers and users)
    cd OFsolvers/birdmultiphaseEulerFoam/
    ./Allwmake
 
-The same steps are done in the ``ci.yml`` (under ``Test-OF - Compile solver``) which can be used as a reference. 
-However, note that ``ci.yml`` compiles the solver in debug mode which is not suitable for production.
+The same steps are done in ``.github/workflows/ci.yml`` (under ``Test-OF - Compile solver``) which can be used as a reference. 
+However, note that ``.github/workflows/ci.yml`` compiles the solver in debug mode which is not suitable for production.
 
 We provide a new drag model ``Grace``, a new interfacial composition model ``Higbie`` and various other models which magnitude can be controlled via an efficiency factor (see `this paper <https://arxiv.org/pdf/2404.19636>`_ for why efficiency factors are useful).