Last improvements to documentation for 0.3.0 (#316)

* Fix Vale * Fix Vale * Bump to vimtor/[email protected] * Fix Vale * Fix docs artifact upload * Update documentation * Improve API documentation. * Typo in examples/__init__.py
ansys · Mar 8, 2023 · 305bcdd · 305bcdd
1 parent 6bd968c
commit 305bcdd
Show file tree

Hide file tree

Showing 38 changed files with 297 additions and 184 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -32,6 +32,14 @@ on:
         required: true
         type: string
         default: ''
+      generate_pdf:
+        description: "Whether to build the PDF doc"
+        type: string
+        default: 'True'
+      debug:
+        description: "Debug verbose mode"
+        type: string
+        default: 'True'
 # Can be called manually
   workflow_dispatch:
     inputs:
@@ -60,6 +68,10 @@ on:
         required: false
         type: string
         default: ''
+      generate_pdf:
+        description: "Whether to build the PDF doc"
+        type: string
+        default: 'True'
 
 env:
   PACKAGE_NAME: ansys-dpf-post
@@ -169,21 +181,23 @@ jobs:
       - name: "Upload Documentation Build log"
         uses: actions/[email protected]
         with:
-          name: doc-${{inputs.PACKAGE_NAME}}-log
+          name: doc-${{env.PACKAGE_NAME}}-log
           path: docs/*.txt
-        if: inputs.debug == 'false'
+        if: always()
 
       - name: "Zip HTML Documentation"
-        uses: vimtor/action-zip@v1
+        uses: vimtor/action-zip@v1.1
         with:
           files: docs/build/html
-          dest: HTML-doc-${{inputs.PACKAGE_NAME}}.zip
+          dest: HTML-doc-${{env.PACKAGE_NAME}}.zip
+        if: always()
 
       - name: "Upload HTML Documentation"
         uses: actions/upload-artifact@v3
         with:
-          name: HTML-doc-${{inputs.PACKAGE_NAME}}
-          path: HTML-doc-${{inputs.PACKAGE_NAME}}.zip
+          name: HTML-doc-${{env.PACKAGE_NAME}}
+          path: HTML-doc-${{env.PACKAGE_NAME}}.zip
+        if: always()
 
       - name: "Find PDF Documentation"
         shell: bash
@@ -197,18 +211,18 @@ jobs:
           echo "Found PDF doc: ${files[0]}"
 
       - name: "Zip PDF Documentation"
-        uses: vimtor/action-zip@v1
+        uses: vimtor/action-zip@v1.1
         if: ${{ inputs.generate_pdf == 'true' }}
         with:
           files: docs/build/latex/${{ steps.pdf.outputs.PDF_file }}
-          dest: PDF-doc-${{inputs.PACKAGE_NAME}}.zip
+          dest: PDF-doc-${{env.PACKAGE_NAME}}.zip
 
       - name: "Upload PDF Documentation"
         uses: actions/[email protected]
         if: inputs.generate_pdf == 'true'
         with:
-          name: PDF-doc-${{inputs.PACKAGE_NAME}}
-          path: PDF-doc-${{inputs.PACKAGE_NAME}}.zip
+          name: PDF-doc-${{env.PACKAGE_NAME}}
+          path: PDF-doc-${{env.PACKAGE_NAME}}.zip
 
       - name: "Kill all servers"
         uses: pyansys/pydpf-actions/[email protected]

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# DPF-Post - Ansys Data Post-Processing Framework
+# PyDPF-Post - Ansys Data Post-Processing Framework
 [![PyAnsys](https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC)](https://docs.pyansys.com/)
 [![Python](https://img.shields.io/pypi/pyversions/ansys-dpf-post?logo=pypi)](https://pypi.org/project/ansys-dpf-post/)
 [![pypi](https://badge.fury.io/py/ansys-dpf-post.svg?logo=python&logoColor=white)](https://pypi.org/project/ansys-dpf-post)
@@ -17,15 +17,13 @@ be found by visiting [PyDPF-Core
 GitHub](https://github.com/pyansys/pydpf-core).  Use ``ansys-dpf-core`` for
 building more advanced and customized workflows using Ansys DPF.
 
-
 ## Documentation
 
-Visit the [DPF-Post Documentation](https://postdocs.pyansys.com) for a
+Visit the [PyDPF-Post Documentation](https://postdocs.pyansys.com) for a
 detailed description of the package, or see the [Examples
 Gallery](https://postdocs.pyansys.com/examples/index.html) for more
 detailed examples.
 
-
 ## Installation
 
 Install this repository with:
@@ -42,11 +40,10 @@ cd pydpf-post
 pip install . --user
 ```
 
-
 ## Brief Demo
 
-Provided you have ANSYS 2023 R1 installed, a DPF server will start
-automatically once you start using pyDPF-Post.
+Provided you have ANSYS 2023 R1 installed, a DPF server starts
+automatically once you start using PyDPF-Post.
 Loading a simulation to extract and post-process results:
 
 ```pycon
@@ -56,6 +53,7 @@ Loading a simulation to extract and post-process results:
 >>> displacement = simulation.displacement()
 >>> print(displacement)
 ```
+```pycon
              results         U
               set_id         3
       node      comp          
@@ -66,7 +64,7 @@ Loading a simulation to extract and post-process results:
                    Y  1.44e-03
                    Z  5.31e-06
        ...
-
+```
 ```pycon
 >>> displacement.plot()
 ```
@@ -89,7 +87,6 @@ tools:
 ```
 ![Example Stress plot Crankshaft](https://github.com/pyansys/dpf-post/raw/master/docs/source/images/crankshaft_stress.png)
 
-
 ## License
 
 ``PyDPF-Post`` is licensed under the MIT license.  For more information, see the

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -217,7 +217,7 @@
     (
         master_doc,
         "PyDPF-Post.tex",
-        "PyAnsys DPF-Post Documentation",
+        "PyAnsys PyDPF-Post Documentation",
         author,
         "manual",
     ),
@@ -228,7 +228,9 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "PyDPF-Post", "PyAnsys DPF-Post Documentation", [author], 1)]
+man_pages = [
+    (master_doc, "PyDPF-Post", "PyAnsys PyDPF-Post Documentation", [author], 1)
+]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -240,7 +242,7 @@
     (
         master_doc,
         "PyDPF-Post",
-        "PyAnsys DPF-Post Documentation",
+        "PyAnsys PyDPF-Post Documentation",
         author,
         "pyansys",
         "",

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -25,13 +25,13 @@ development mode, run:
 Post issues
 -----------
 
-Use the `PyDPF-Post Issues <https://github.com/pyansys/DPF-Post/issues>`_
+Use the `PyDPF-Post Issues <https://github.com/pyansys/pydpf-post/issues>`_
 page to submit questions, report bugs, and request new features.
 
 To reach the PyAnsys support team, email `[email protected] <[email protected]>`_.
 
 View documentation
 ------------------
 Documentation for the latest stable release of PyDPF-Post is hosted at
-`PyDPF Documentation <https://postdocs.pyansys.com/>_.
+`PyDPF Documentation <https://post.docs.pyansys.com/>`_.
 
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
@@ -6,8 +6,11 @@ Getting started
 
 To use the PyDPF-Post API, you must have PyDPF-Core installed. Because you need to
 use a native DPF server, you must also have a local installation of Ansys 2021 R1
-or later. For more information on getting a licensed copy of Ansys, visit the
+or later or of the standalone DPF Server.
+For more information on getting a licensed copy of Ansys, visit the
 `Ansys website <https://www.ansys.com/>`_.
+For more information on getting the standalone DPF Server, visit the
+`PyDPF-Core documentation <https://dpf.docs.pyansys.com/dev/user_guide/getting_started_with_dpf_server.html>`_.
 
 
 .. toctree::

diff --git a/docs/source/getting_started/install.rst b/docs/source/getting_started/install.rst
@@ -50,7 +50,7 @@ and unzip it to the same local directory before running the preceding command ag
 Install in development mode
 ---------------------------
 
-If you want to edit and potentially contribute to DPF-Post,
+If you want to edit and potentially contribute to PyDPF-Post,
 clone the repository and install it using ``pip`` with the ``-e``
 development flag:
 
@@ -66,5 +66,5 @@ Run the following Python code to verify your PyDPF-Post installation:
 
    from ansys.dpf import post
    from ansys.dpf.post import examples
-   solution = post.load_solution(examples.simple_bar)
-   print(solution)
+   simulation = post.load_simulation(examples.simple_bar)
+   print(simulation)
diff --git a/docs/source/images/crankshaft_stress_xx.png b/docs/source/images/crankshaft_stress_xx.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,15 +10,15 @@ The Python `ansys-dpf-post` package provides a high level, physics oriented API
 Loading a simulation (defined by its result files) allows you to extract simulation metadata as well
 as results and apply postprocessing operations on it.
 
-This module leverages the PyDPF-Core project's ``ansys-dpf-core`` package and can
-be found by visiting [PyDPF-Core GitHub](https://github.com/pyansys/pydpf-core).
+This module leverages the PyDPF-Core project's ``ansys-dpf-core`` package which can
+be found by visiting `PyDPF-Core GitHub <https://github.com/pyansys/pydpf-core>`_.
 Use ``ansys-dpf-core`` for building more advanced and customized workflows using Ansys DPF.
 
 
 Brief demo
 ~~~~~~~~~~
 
-Provided you have ANSYS 2023 R1 installed, a DPF server will start
+Provided you have Ansys 2023 R1 installed, a DPF server starts
 automatically once you start using PyDPF-Post.
 Loading a simulation for a MAPDL result file to extract and post-process results:
 
@@ -87,7 +87,7 @@ Key features
 
 PyDPF-Post is based on DPF, whose data framework localizes loading and
 postprocessing on the DPF server, enabling rapid postprocessing workflows
-because they are written in C and FORTRAN. Because DPF-Post presents results
+because they are written in C and FORTRAN. Because PyDPF-Post presents results
 in a Pythonic manner, you can rapidly develop simple or complex postprocessing
 scripts.
 

diff --git a/docs/source/user_guide/accessing_file_metadata.rst b/docs/source/user_guide/accessing_file_metadata.rst
@@ -4,67 +4,93 @@
 Browse result metadata
 **********************
 
-In addition to the :class:`DpfSolution <ansys.dpf.post.dpf_solution.DpfSolution>`
+In addition to the :class:`Simulation <ansys.dpf.post.simulation.Simulation>`
 object being the entry point for browsing the contents of a result file, it provides
 important metadata, such as the analysis type and the available results.
 
 Here is how you browse result metadata:
 
 .. code:: python
 
-    Instantiate the solution object
+    Instantiate the simulation object
 
     >>> from ansys.dpf import post
     >>> from ansys.dpf.post import examples
-    >>> solution = post.load_solution(examples.multishells_rst)
+    >>> simulation = post.load_simulation(examples.multishells_rst)
 
     Browse result metadata
 
-    >>> result_info = solution.get_result_info()
-    >>> print(result_info)
+    >>> print(simulation)
+    Static Mechanical Simulation.
+
+
+    Data Sources
+    ------------------------------
+    DPF  DataSources:
+      Result files:
+         result key: rst and path: d:\ansysdev\sandbox\pydpf-core\src\ansys\dpf\core\examples\model_with_ns.rst
+      Secondary files:
+
+
+    DPF Model
+    ------------------------------
     Static analysis
-    Unit system: Metric (m, kg, N, s, V, A)
-    Physics Type: Mecanic
+    Unit system: MKS: m, kg, N, s, V, A, degC
+    Physics Type: Mechanical
     Available results:
-         -  displacement
-         -  force
-         -  stress
-         -  volume
-         -  energy_stiffness_matrix
-         -  hourglass_energy
-         -  thermal_dissipation_energy
-         -  kinetic_energy
-         -  co_energy
-         -  incremental_energy
-         -  strain
-         -  temperature
-
-
-DPF-Post supports four different analysis types:
+         -  displacement: Nodal Displacement
+         -  reaction_force: Nodal Force
+         -  stress: ElementalNodal Stress
+         -  elemental_volume: Elemental Volume
+         -  stiffness_matrix_energy: Elemental Energy-stiffness matrix
+         -  artificial_hourglass_energy: Elemental Hourglass Energy
+         -  thermal_dissipation_energy: Elemental thermal dissipation energy
+         -  kinetic_energy: Elemental Kinetic Energy
+         -  co_energy: Elemental co-energy
+         -  incremental_energy: Elemental incremental energy
+         -  elastic_strain: ElementalNodal Strain
+         -  structural_temperature: ElementalNodal Temperature
+    ------------------------------
+    DPF  Meshed Region:
+      7079 nodes
+      4220 elements
+      Unit: m
+      With solid (3D) elements, shell (2D) elements, shell (3D) elements
+    ------------------------------
+    DPF  Time/Freq Support:
+      Number of sets: 1
+    Cumulative     Time (s)       LoadStep       Substep
+    1              1.000000       1              1
+
+
+PyDPF-Post supports four different analysis types for mechanical results:
 
 * Static analysis
 * Modal analysis
 * Harmonic analysis
 * Transient analysis
 
+The legacy Solution object also supports thermal and electrical results.
+
 Mesh
 ----
-From the ``Solution`` object, you can also access the mesh:
+From the ``Simulation`` object, you can also access the mesh:
 
 .. code:: python
 
-    Instantiate the solution object
+    Instantiate the simulation object
 
     >>> from ansys.dpf import post
     >>> from ansys.dpf.post import examples
-    >>> solution = post.load_solution(examples.multishells_rst)
+    >>> simulation = post.load_simulation(examples.multishells_rst)
 
     Access the mesh
 
-    >>> mesh = solution.mesh
+    >>> mesh = simulation.mesh
     >>> print(mesh)
-    Meshed Region
-    	7079 nodes
-    	4220 elements
-    	Unit: m
+    DPF  Mesh:
+      7079 nodes
+      4220 elements
+      Unit: m
+      With solid (3D) elements, shell (2D) elements, shell (3D) elements