Docs/user guide (#14)

* gitignore updated

* user_guide files added

* speed -> velocity

* solution doc string fix

* old user guide index file removed

* API files added

* doc string stress update

* user guide and API references added

* fix for get result info

* fixes for generation with sphinx

* rth files added in user guide

* accesing_result .rst file update

* misc_results file updated

* _plot_chart removed (need to be discussed)

* examples order changed

* thermal analysis and mechanics analysis

* extensions removed

* suggested editorial improvements

* suggested editorial improvements

* suggested editorial improvements (API & index.rst)

* cleaned up code docgen

* touch log file to avoid tail on non-existing file

Co-authored-by: jazztekk <[email protected]>
Co-authored-by: Alex Kaszynski <[email protected]>

Author: 3 people

.ci/azure-pipelines.yml

@@ -132,6 +132,7 @@ jobs:
         set -ex
         echo $(PAT) | docker login -u $(GH_USERNAME) --password-stdin docker.pkg.github.com
         docker pull $(DPF_IMAGE)
+        touch log.txt
         docker run --restart always --name dpf -v `pwd`:/dpf -v /tmp:/dpf/_cache -p $(DPF_PORT):50054 $(DPF_IMAGE) > log.txt &
         grep -q 'server started on ip' <(timeout 60 tail -f log.txt)
         python -c "from ansys.dpf import core as dpf; dpf.connect_to_server(port=$(DPF_PORT)); print('Python Connected')"

.github/workflows/ci-build.yml

@@ -50,6 +50,7 @@ jobs:
       - name: Pull, launch, and validate DPF service
         run: |
           echo $PAT | docker login -u $GH_USERNAME --password-stdin docker.pkg.github.com
+          touch log.txt
           docker run --restart always --name dpf -v `pwd`:/dpf -v /tmp:/dpf/_cache -p $DPF_PORT:50054 $DPF_IMAGE > log.txt &
           grep -q 'server started on ip' <(timeout 60 tail -f log.txt)
           python -c "from ansys.dpf.post import examples;from ansys.dpf import core;print(core.Model(examples.simple_bar))"

.gitignore

@@ -20,6 +20,8 @@ __pycache__
 #other
 /perso
 /examples/Jupyter lab/.ipynb_checkpoints
+*checkpoint.py
+*checkpoint.ipynb
 
 # compiled documentation
 docs/_build

ansys/dpf/post/dpf_solution.py

@@ -48,23 +48,14 @@ def get_result_info(self):
         
         Examples
         --------
-        The following code:
         >>> from ansys.dpf import post
         >>> result = post.result("file.rst")
-        >>> print(result.get_result_info())
-        
-        Will return:
-            Static analysis
-            Unit system: Metric (m, kg, N, s, V, A)
-            Physics Type: Mecanic
-            Available results:
-                 -  displacement                                        
-                 -  volume                                        
+        >>> print(result.get_result_info())                                     
         """
         return self._model.metadata.result_info
 
     def __str__(self):
-        txt = '%s result object.' % self._model.metadata.result_info.analysis_type.capitalize() +\
+        txt = '%s solution object.' % self._model.metadata.result_info.analysis_type.capitalize() +\
         '\n\n\nData Sources\n------------------------------\n'
         ds_str = self._data_sources.__str__()
         txt += ds_str

ansys/dpf/post/misc_results.py

@@ -270,7 +270,7 @@ def plot_contour(self, display_option: str = "time", option_id=1,
             pl.plot_contour(new_fields_container, off_screen=off_screen,
                             notebook=notebook, **kwargs)
 
-    def plot_chart(self):
+    def _plot_chart(self):
         """Plot the minimum/maximum result values over time.
 
         This method works if the time_freq_support contains

ansys/dpf/post/result_data.py

@@ -15,9 +15,6 @@ class Stress(Tensor):
     >>> from ansys.dpf.post import examples
     >>> solution = post.load_solution(examples.multishells_rst)
     >>> stress = solution.stress(location=post.locations.nodal, time_scoping=[1])
-
-    Extract the princ
-
     """
     def __init__(self, **kwargs):
         super().__init__(**kwargs)

ansys/dpf/post/stress.py

@@ -14,6 +14,9 @@ h1, h2, h3, h4, h5, h6 {
     font-family: 'Source Sans Pro', sans-serif;
 }
 
+.navbar-toggler-icon {
+    background-image: url("data:image/svg+xml;charset=utf8,%3Csvg viewBox='0 0 32 32' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath stroke='rgba(255,255,255, 0.9)' stroke-width='2' stroke-linecap='round' stroke-miterlimit='10' d='M4 8h24M4 16h24M4 24h24'/%3E%3C/svg%3E") !important;
+}
 
 .sig-prename {
     color: var(--ansysBronze);

docs/source/_static/css/ansys.css

@@ -1,54 +1,24 @@
-.. _ref_api_index:
+============
+DPF-Post API
+============
+This guide provides an overview of the DPF-Post API.
 
-API Reference
-=============
-Details of the DPF API.
+DPF-Post leverages three main categories of objects: 
 
+1. **Solution**: it is the entry point to the results file, its
+   metadata and contents.
 
-Solution Object
----------------
-The solution object instantiates an object that is built on the result
-file.  Use the following code to instantiate a solution object.
+2. **Result**: it provides access to specific result types, in
+   accordance with the type of analysis.
 
-.. code:: python
+3. **ResultData**: it provides access to the actual data values and
+   closely relates to the DPF-Core "Fields Container" concept.
 
-    >>> from ansys.dpf import post
-    >>> from ansys.dpf.post import examples
-    >>> solution = post.load_solution(examples.multishells_rst)
 
-
-Result Object
--------------
-The result object can be manipulated to get different result data.
-
-.. code:: python
-
-    >>> from ansys.dpf import post
-    >>> from ansys.dpf.post import examples
-    >>> solution = post.load_solution(examples.multishells_rst)
-    >>> # Displacement result object
-    >>> displacement = solution.displacement()
-    >>> # Stress result object
-    >>> stress = solution.stress()
-    >>> # Elastic strain result object
-    >>> elastic_strain = solution.elastic_strain()
-
-
-ResultData Class
-----------------
-The ``ResultData`` class is instantiated from a result object.  It
-enables easy access to the data contained within the result
-object. The following example shows how to get an instance of
-``ResultData``.
-    
-.. code:: python
-
-    >>> from ansys.dpf import post
-    >>> solution = post.load_solution(r'../../../testfiles/tests/model_with_ns.rst')
-    >>> displacement = solution.displacement()
-    >>> result = displacement.vector
-    >>> # access the data
-    >>> vector.get_data_at_field(0)
-    
-.. autoclass:: ansys.dpf.post.result_data.ResultData
-    :members:
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+  
+   solution
+   result_object
+   result_data

docs/source/api/index.rst

@@ -0,0 +1,22 @@
+.. _ref_api_result_data:
+
+*****************
+ResultData object
+*****************
+
+The ``ResultData`` object is obtained from a ``Result``.  It provides
+access to the result values contained within, as shown in the
+following example:
+    
+.. code:: python
+
+    >>> from ansys.dpf import post
+    >>> from ansys.dpf.post import examples
+    >>> solution = post.load_solution(examples.multishells_rst)
+    >>> displacement = solution.displacement()
+    >>> result = displacement.vector
+    >>> # access the data
+    >>> vector.get_data_at_field(0)
+    
+.. autoclass:: ansys.dpf.post.result_data.ResultData
+    :members: