Reorganizing the headers (#1689)

* Adding option to publish to dev from the CI before merging

* Reorg in docs

* Fixing vale

* Resetting cache

* Fixing doc building warnings.

* fixing links

* Apply suggestions from code review

Co-authored-by: Revathy Venugopal <[email protected]>

* Apply suggestions from code review from Kathy

Thank you a lot Kathy!

Co-authored-by: Kathy Pippert <[email protected]>

* Disabling Windows tests.

* Using an if instead of comments

* Update doc/source/user_guide/troubleshoot.rst

* line

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Kathy Pippert <[email protected]>

* removing the graphviz

* fixing pdf building

Co-authored-by: Revathy Venugopal <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>

Author: 3 people

.github/workflows/ci.yml

@@ -3,6 +3,11 @@ name: CI
 on:
   pull_request:
   workflow_dispatch:
+    inputs:
+      test_dev_docs:
+        description: 'Publish the documentation before merging'
+        type: boolean
+        required: false
   push:
     tags:
       - "*"
@@ -97,8 +102,8 @@ jobs:
 
       - name: "Install OS packages"
         run: |
-          sudo apt update
-          sudo apt install zip pandoc libgl1-mesa-glx xvfb texlive-latex-extra latexmk
+          sudo apt update 
+          sudo apt install zip pandoc libgl1-mesa-glx xvfb texlive-latex-extra latexmk graphviz
 
       - name: "Cache pip"
         uses: actions/cache@v3
@@ -552,7 +557,7 @@ jobs:
 
   upload_dev_docs:
     name: "Upload dev documentation"
-    if: github.ref == 'refs/heads/main'
+    if: ${{ github.ref == 'refs/heads/main' || github.event.inputs.publish == 'true' }}
     runs-on: ubuntu-latest
     needs: [docs_build]
     steps:

.github/workflows/nightly-doc-build.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Install OS packages
         run: |
           sudo apt-get update
-          sudo apt-get install libgl1-mesa-glx xvfb pandoc -qy
+          sudo apt-get install libgl1-mesa-glx xvfb pandoc graphviz -qy
 
       - name: Install ansys-mapdl-core
         run: |

doc/Makefile

@@ -38,7 +38,7 @@ pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	python validate_png.py  # clean-up GIFs mislabeled as PNG
 	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
-	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1
+	(test -f $(BUILDDIR)/latex/pymapdl-Documentation-*.pdf && echo pdf exists) || exit 1
 
 checklinks:
 	$(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) $(LINKCHECKDIR)

doc/source/contribution_and_api/building_example.rst renamed to doc/source/api/building_example.rst

@@ -0,0 +1,38 @@
+
+.. _ref_index_api:
+
+API reference
+=============
+
+This page gives an overview of the API of several public PyMAPDL
+classes, functions, and attributes. You can find them
+on the left sidebar.
+
+While these methods might include some MAPDL commands, they are generally
+specific to PyMAPDL methods and classes. PyMAPDL methods extend existing
+MAPDL methods in a Pythonic manner. For a mapping of MAPDL commands to
+PyMAPDL, see :ref:`ref_mapdl_commands`.
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   commands
+   database
+   geometry
+   helper
+   inline
+   krylov
+   logging
+   mapdl
+   math
+   mesh
+   parameters
+   plotting
+   pool
+   post
+   solution
+   xpl
+   building_example
+   unit_testing

doc/source/contribution_and_api/commands.rst renamed to doc/source/api/commands.rst

@@ -63,6 +63,7 @@
     "sphinx_copybutton",
     "sphinx_gallery.gen_gallery",
     "sphinxemoji.sphinxemoji",
+    "sphinx.ext.graphviz",
 ]
 
 # Intersphinx mapping
@@ -205,6 +206,11 @@
             "url": "https://github.com/pyansys/pymapdl/discussions",
             "icon": "fa fa-comment fa-fw",
         },
+        {
+            "name": "Contribute",
+            "url": "https://mapdl.docs.pyansys.com/release/dev/getting_started/contribution.html",
+            "icon": "fa fa-wrench",
+        },
     ],
     "switcher": {
         "json_url": f"https://{cname}/release/versions.json",

doc/source/contribution_and_api/database.rst renamed to doc/source/api/database.rst

@@ -1,8 +1,8 @@
 .. _ref_contributing:
 
-====================
-Contributing and API
-====================
+============
+Contributing
+============
 
 Overall guidance on contributing to a PyAnsys library appears in the
 `Contributing <dev_guide_contributing_>`_ topic
@@ -102,40 +102,3 @@ This way, it's not possible for you to push code that fails the style checks. Fo
   flake8...................................................................Passed
   codespell................................................................Passed
 
-
-.. _ref_index_api:
-
-API reference
-=============
-This page gives an overview of the API of several public PyMAPDL
-classes, functions, and attributes. You can find them
-on the left sidebar.
-
-While these methods might include some MAPDL commands, they are generally
-specific to PyMAPDL methods and classes. PyMAPDL methods extend existing
-MAPDL methods in a Pythonic manner. For a mapping of MAPDL commands to
-PyMAPDL, see :ref:`ref_mapdl_commands`.
-
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-
-   commands
-   database
-   geometry
-   helper
-   inline
-   krylov
-   logging
-   mapdl
-   math
-   mesh
-   parameters
-   plotting
-   pool
-   post
-   solution
-   xpl
-   building_example
-   unit_testing

doc/source/contribution_and_api/geometry.rst renamed to doc/source/api/geometry.rst

@@ -1,8 +1,8 @@
 .. _pymapdl_docker:
 
-************************
-Use MAPDL through Docker
-************************
+*****************
+Docker containers
+*****************
 You can run MAPDL within a container on any OS using Docker and
 connect to it via PyMAPDL.
 
@@ -17,7 +17,9 @@ in a containerized environment such as Docker or Singularity:
 Configure the Docker registry
 =============================
 
-There is a Docker image hosted on the 
+**Only for images in private repositories.**
+
+There are several Docker images hosted on the 
 `PyMAPDL GitHub <pymapdl_repo_>`_ repository that you
 can download using your GitHub credentials.
 
@@ -43,38 +45,79 @@ with:
     cat GH_TOKEN.txt | docker login ghcr.io -u $GH_USERNAME --password-stdin
 
 
+.. _run_an_mapdl_image:
+
 Run an MAPDL image
 ===================
 
 You can now launch MAPDL directly from Docker with a short script or
-directly from the command line. Because this image contains no license
-server, you must enter your license server IP address in the
-``LICENSE_SERVER`` environment variable. With that, you can launch
-MAPDL with:
-
-.. code::
+directly from the command line.
+You can then use your host Python environment to connect to that MAPDL
+instance.
+
+.. graphviz::
+
+    digraph {
+      node [];
+      subgraph cluster_frontend {
+        label="*HOST*";
+        Python;
+      subgraph cluster_backend {
+        MAPDL;
+        label="*DOCKER*";
+        }
+      }
+      Python -> MAPDL
+      MAPDL -> Python
+    }
+
+Because this image does not contain a license server, you must enter your
+license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable. 
+
+Additionally, you run a Docker image of PyMAPDL with:
 
-    [email protected]
-    VERSION=v21.1.0
+.. code:: pwsh
 
-    IMAGE=ghcr.io/pyansys/pymapdl/mapdl:$VERSION
-    docker run -e ANSYSLMD_LICENSE_FILE=$LICENSE_SERVER -p 50052:50052 $IMAGE -smp
+    docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt
 
 First time you run it, Docker logins into the *ghcr.io* registry and
-pulls the image which can take some time.
+pulls the image, which can take some time.
 There are several images in the registry, each corresponding to a different
-version of MAPDL. It is recommended to use the latest version of MAPDL for
-the Ubuntu systems (any image tagged as ``Ubuntu``).
+version of MAPDL. For Ubuntu systems (any image tagged as ``Ubuntu``), you should
+use the latest version of MAPDL.
+
+To rerun it, you should restart the container or just delete it and run it again using:
+
+.. code:: pwsh
+
+    docker stop mapdl
+    docker container prune
+
+    docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt
+
+You can use the Docker flag ``--rm`` to automatically clean up the container
+and remove the file system when the container exits.
 
-Note that port `50052` (local to the container) is being mapped to
-50052 on the host. This makes it possible to launch several MAPDL
-instances with different port mappings to allow for multiple instances
-of MAPDL.
+This creates a log file (``log.txt``) in your current directory location.
+
+Notice that the WSL internal gRPC port (``50052``) is being mapped to a
+different Windows host port (``50053``) to avoid port conflicts with local
+MAPDL instances running on the host.
+You could additionally launch more Docker containers in different ports if
+you want to run multiple simulations at the same time.
+The module ``ansys-mapdl-core-pool`` does not work when you are connecting
+to an MAPDL Docker image.
+
+.. note:: Ensure that your port ``50053`` is open in your firewall.
 
 You can provide additional command line parameters to MAPDL by simply
 appending to the Docker command. 
 For example, you can increase the number of processors (up to the
-number available on the host machine) with the `-np` switch.
+number available on the host machine) with the ``-np`` switch.
+
+You should use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``)
+to run the preceding commands all at once.
+
 
 Once you have launched MAPDL you should see:
 
@@ -90,6 +133,7 @@ Once you have launched MAPDL you should see:
     Server listening on : 0.0.0.0:50052
 
 
+
 Using ``docker-compose`` to launch MAPDL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -135,9 +179,12 @@ use:
    The license server is not intended to be used in production. 
    It is only intended for testing/debugging purposes.
    Its access is limited to collaborators of the PyAnsys project.
-   If you would like to have access to it, please contact PyAnsys support at
+   If you would like to have access to the license server, contact PyAnsys support at
    `[email protected] <pyansys_support_>`_.
 
+
+.. _pymapdl_connect_to_MAPDL_container:
+
 Connect to the MAPDL container from Python
 ==========================================
 
@@ -165,6 +212,67 @@ Verify your connection with:
     MAPDL Version:       RELEASE  2021 R1           BUILD 21.0
     PyMAPDL Version:     Version: 0.57.0
 
+
+To connect to an existing MAPDL instance, you can use the :func:`launch_mapdl() <ansys.mapdl.core.launch_mapdl>` method with the argument ``start_instance=False``:
+
+.. code:: python
+
+    from ansys.mapdl.core import launch_mapdl
+
+    mapdl = launch_mapdl(port=50053, start_instance=False) 
+
+
+Because of the linking between host ports and Docker ports (``-p`` argument),
+you do not need to specify the IP address when connecting to a local container.
+However, if you are trying to connect to a WSL local distribution, you must
+specify the IP address of the WSL instance (normally ``127.0.0.1``) because
+no port mapping is done between both.
+
+Here is an example:
+
+.. code:: python 
+
+    from ansys.mapdl.core import Mapdl
+    
+    mapdl = Mapdl(ip='127.0.0.1', port=50053)
+
+
+You can also specify the port and IP address using environment variables that are read when
+launching the MAPDL instance:
+
+.. code:: bash
+
+    export PYMAPDL_START_INSTANCE=False
+    export PYMAPDL_PORT=50053
+    export PYMAPDL_IP=127.0.0.1
+
+
+
+Launch Docker with UPF capabilities
+===================================
+
+If you want to specify a custom Python UPF routine, you must have the
+environment variables ``ANS_USER_PATH`` and ``ANS_USE_UPF`` defined. The
+former should be equal to the path where the UPF routines are located, and the
+latter should be equal to ``TRUE``.
+
+In WSL, you can do this using:
+
+.. code:: bash
+
+    export ANS_USER_PATH=/home/user/UPFs # Use your own path to your UPF files.
+    export ANS_USE_UPF=TRUE
+
+You can then run the Docker image with:
+
+.. code:: bash
+
+    docker run -e [email protected] -e ANS_USER_PATH='/ansys_jobs/upf' -e ANS_USE_UPF='TRUE' --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp  1>log.txt
+
+.. warning:: The use of UPFs with Docker images or PyMAPDL is still in the alpha state.
+
+
+
 Additional considerations
 =========================
 

doc/source/contribution_and_api/helper.rst renamed to doc/source/api/helper.rst

@@ -13,11 +13,15 @@ For more information on getting a licensed copy of Ansys, visit
    :hidden:
    :maxdepth: 2
 
-   running_mapdl
+   learning
    versioning
+   running_mapdl
    docker
-   using_julia
    wsl
+   using_julia
+   faq
+   contribution
+
 
 ************
 Installation