Various improvements to streamline example code (#350)

* Add self contained example that builds an ACP model from a cdb file that just contains the mesh.
* Add workflow helper to simplify file transfer operations
* Move to_pyvista function one level lower so that the user does not have to specify the component enums.
*Add tree printer

closes #343
closes #232

Author: janvonrickenbach

.github/workflows/ci_cd.yml

@@ -270,6 +270,11 @@ jobs:
       - name: Build HTML
         run: |
           xvfb-run poetry run make -C doc html SPHINXOPTS="-W --keep-going -v"
+        env:
+          PYMAPDL_PORT: "50557"
+          PYMAPDL_START_INSTANCE: "FALSE"
+          PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT: "50558"
+
 
       - name: Stop and clean up MAPDL and DPF servers
         run: |

README.rst

@@ -153,19 +153,9 @@ You will need to follow these steps:
 
         poetry shell
 
-.. TODO: If we add tox, add instructions on its use here.
-
-.. 6. Verify your development installation by running:
-
-..     .. code-block:: bash
-
-..         tox
-
 Testing
 ^^^^^^^
 
-.. TODO: If we add tox, add instructions on its use here.
-
 The PyACP test suite uses `pytest`_. You can run it with
 
 .. code-block:: bash
@@ -210,16 +200,9 @@ need to create a commit without running the hooks, you can skip them with ``git
 
 Documentation
 ^^^^^^^^^^^^^
-
-To build the documentation, DPF Composites and MAPDL servers need to be running:
-
-.. code-block:: bash
-
-    docker-compose -f docker-compose/docker-compose-extras.yaml up -d
-
-In addition, the PyACP server needs to be configured via ``ansys-launcher``, see `Launching ACP <launching_server>`_ above.
-
-It can then be built using `Sphinx`_.
+Before generating the documentation, configure the PyACP server via the
+``ansys-launcher``, see `Launching ACP <launching_server>`_ above.
+If Ansys is installed the examples can directly built with `Sphinx`_.
 
 On Linux & MacOS:
 
@@ -235,6 +218,20 @@ On Windows:
 
 The generated HTML files can be viewed with the browser of your choice.
 
+Alternatively you can build the documentation by starting a mapdl and pydpf-composites docker
+container. First ensure that you have accepted the DPF Preview License Agreement by setting the
+ANSYS_DPF_ACCEPT_LA environment variable to Y
+(see `DPF Preview License Agreement <https://dpf.docs.pyansys.com/version/stable/user_guide/getting_started_with_dpf_server.html#dpf-preview-license-agreement>`_
+). In addition the  ANSYSLMD_LICENSE_FILE environment variable needs be set to a
+valid license server (e.g [email protected]). Then start the docker containers with:
+
+.. code-block:: bash
+
+    docker-compose -f docker-compose/docker-compose-extras.yaml up -d
+
+Then build the documentation with the `Sphinx`_ commands mentioned above.
+
+
 Distribution
 ^^^^^^^^^^^^
 
@@ -264,4 +261,3 @@ License
 .. _pre-commit: https://pre-commit.com/
 .. _pytest: https://docs.pytest.org/en/stable/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
-.. _tox: https://tox.wiki/

doc/source/api/index.rst

@@ -15,3 +15,4 @@ and attributes.
     linked_object_definitions
     material_property_sets
     other_types
+    workflow

doc/source/api/tree_objects.rst

@@ -34,3 +34,5 @@ ACP objects
     ProductionPly
     AnalysisPly
     Sensor
+    ScalarData
+    VectorData

doc/source/api/workflow.rst

@@ -0,0 +1,16 @@
+Workflow
+--------
+
+.. currentmodule:: ansys.acp.core
+
+.. autosummary::
+    :toctree: _autosummary
+
+    ACPWorkflow
+    get_composite_post_processing_files
+    get_model_tree
+    get_dpf_unit_system
+    print_model
+
+
+

doc/source/examples/index.rst

@@ -6,6 +6,3 @@ Examples
 
 .. include:: gallery_examples/index.rst
    :start-line: 2
-
-:doc:`./others/local_pyacp_executable` demonstrates running the
-PyACP server from a local executable instead of in a Docker container