Documentation improvements

.codespellrc

@@ -1,4 +1,4 @@
 [codespell]
 skip = *.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,\#*,build,./docker/mapdl/v*,./factory/*,./ansys/mapdl/core/mapdl_functions.py,PKG-INFO,*.mypy_cache/*,./docker/mapdl/*,./_unused/*
-ignore-words-list = delet,appen,parm,pres,WAN,filname,ans,tread,wan,levl,mater,aadd,extrem,imagin,ist,nin,sord,struc,emiss,vise,sur,larg,smal
+ignore-words-list = delet,appen,parm,pres,WAN,filname,ans,tread,wan,levl,mater,aadd,extrem,imagin,ist,nin,sord,struc,emiss,vise,sur,larg,smal,ect
 quiet-level = 3

.github/workflows/ci.yml

@@ -24,10 +24,10 @@ env:
   # You should go up in number, if you go down (or repeat a previous value)
   # you might end up reusing a previous cache if it haven't been deleted already.
   # It applies 7 days retention policy by default.
-  RESET_PIP_CACHE: 3
-  RESET_EXAMPLES_CACHE: 3
-  RESET_DOC_BUILD_CACHE: 3
-  RESET_AUTOSUMMARY_CACHE: 3
+  RESET_PIP_CACHE: 9
+  RESET_EXAMPLES_CACHE: 9
+  RESET_DOC_BUILD_CACHE: 9
+  RESET_AUTOSUMMARY_CACHE: 9
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

README.rst

@@ -273,9 +273,10 @@ the most recent citation.
 
 License and acknowledgments
 ---------------------------
-``PyMAPDL`` is licensed under the MIT license.
+``PyMAPDL`` is licensed under
+`the MIT license <https://github.com/pyansys/pymapdl/blob/main/LICENSE>`_.
 
-This module, ``ansys-mapdl-core`` makes no commercial claim over Ansys
+``ansys-mapdl-core`` package makes no commercial claim over Ansys
 whatsoever.  This tool extends the functionality of ``MAPDL`` by
 adding a Python interface to the MAPDL service without changing the
 core behavior or license of the original software.  The use of the

doc/source/_static/custom.css

@@ -1,17 +1,17 @@
 @import url("default.css");
 
-.red {
+.red-text {
     color: red;
 }
 
-.green {
+.green-text {
     color: green;
 }
 
-.blue {
+.blue-text {
     color: blue;
 }
 
-.yellow {
-  color: yellow;
+.yellow-text {
+    color: yellow;
 }

doc/source/conf.py

@@ -208,9 +208,11 @@
 }
 
 html_context = {
+    "display_github": True,  # Integrate GitHub
     "github_user": "pyansys",
     "github_repo": "pymapdl",
     "github_version": "main",
+    "doc_path": "doc/source",
 }
 # -- Options for HTMLHelp output ---------------------------------------------
 

doc/source/examples/index.rst

@@ -26,7 +26,7 @@ Here are a series of examples using MAPDL with ``ansys-mapdl-core``.
     technology_showcase_examples/techdemo-20/20-example-technology-showcase-dynamic-simulation-PCB
     technology_showcase_examples/techdemo-28/ex_28-tecfricstir
 
-.. include:: technology_showcase_examples/README.txt
+.. include:: technology_showcase_examples/index.rst
    :start-line: 2
 
 

doc/source/examples/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.rst

@@ -1,10 +1,12 @@
 .. _tech_demo_28:
 
-.. role:: red
+.. role:: red-text
 
-.. role:: blue
+.. role:: blue-text
 
-.. role:: green
+.. role:: green-text
+
+.. role:: yellow-text
 
 Friction Stir Welding (FSW) Simulation
 ***************************************
@@ -456,7 +458,7 @@ model the contact surface on the top surface of the workpiece, and the
     p.show()
 
 **Figure 28.4: Contact Pair Between Tool and Workpiece.**
-``CONTA174`` in :blue:`blue`, and ``TARGE170`` in :red:`red`.
+``CONTA174`` in :blue-text:`blue`, and ``TARGE170`` in :red-text:`red`.
 
 
 Two real constants are specified to model friction-induced heat generation.
@@ -576,7 +578,7 @@ The following contact settings are used for the ``CONTA174`` elements:
 
 **Figure 28.5: Rigid Surface Constrained.**
 Pilot node or master with applied boundary conditions and the constrained 
-top surface of the tool (:blue:`blue`).**
+top surface of the tool (:blue-text:`blue`).**
 
 
 .. code:: python
@@ -781,7 +783,7 @@ to the backing plate.
     pl.show()
 
 **Figure 28.6: Thermal Boundary Conditions.**
-Convection loads (:red:`red`) and conduction loads (:yellow:`yellow`)
+Convection loads (:red-text:`red`) and conduction loads (:yellow-text:`yellow`)
 
 Available data suggest that the value of the convection coefficient lies
 between 10 and 30 W/m2 °C for the workpiece surfaces, except for the bottom
@@ -864,7 +866,7 @@ perpendicular direction (z direction).
     pl.show()
 
 **Figure 28.7: Mechanical Boundary Conditions:**
-X-direction (``UX``) in :red:`red`, Y-direction (``UY``) in :green:`green`, and Z-direction (``UZ``) in :blue:`blue`.
+X-direction (``UX``) in :red-text:`red`, Y-direction (``UY``) in :green-text:`green`, and Z-direction (``UZ``) in :blue-text:`blue`.
 
 
 .. code:: python 
@@ -1398,7 +1400,7 @@ load step is shown in the following figure:
 
 
 **Figure 28.21: Contact Status at Interface with Bonding Temperature 1000 °C**
-Elements can be in near-contact (:blue:`blue`), sliding (:green:`green`) or sticking (:red:`red`) states.
+Elements can be in near-contact (:blue-text:`blue`), sliding (:green-text:`green`) or sticking (:red-text:`red`) states.
 
 
 The sticking portion of the interface shows the bonding or welding region of
@@ -1416,7 +1418,7 @@ welding region would increase, as shown in this figure:
    pl.show() 
 
 **Figure 28.22: Contact Status at Interface with Bonding Temperature 900 °C**
-Elements can be in near-contact (:blue:`blue`), sliding (:green:`green`) or sticking (:red:`red`) states.
+Elements can be in near-contact (:blue-text:`blue`), sliding (:green-text:`green`) or sticking (:red-text:`red`) states.
 
 
 28.7.4. Heat Generation

doc/source/getting_started/versioning.rst

@@ -5,42 +5,109 @@ The PyMAPDL project attempts to maintain compatibility with legacy
 versions of MAPDL while allowing for support of faster and better
 interfaces with the latest versions of MAPDL.
 
+There are three interfaces PyMAPDL can use to connect to MAPDL.
 
-Ansys 2021 R1 and later
-~~~~~~~~~~~~~~~~~~~~~~~
-Ansys 2020 R1 and later support the latest gRPC interface, allowing
+
+
+gRPC interface
+~~~~~~~~~~~~~~
+This is the default and preferred interface to connect to MAPDL.
+Ansys 2020 R1 and later support the latest `gRPC interface <grpc_>`_, allowing
 for remote management of MAPDL with rapid streaming of mesh, results,
-and files from the MAPDL service. If you have the applicable
-license, you can install and use MAPDL with Docker, enabling you
+and files from the MAPDL service.
+This interface also allows to work with a docker image.
+If you have the applicable license, you can install and use 
+MAPDL within Docker, enabling you
 to run and solve even on officially unsupported platforms like Mac
-OS.
+OS. For more information visit :ref:`pymapdl_docker`.
+
 
+Legacy interfaces
+~~~~~~~~~~~~~~~~~
+
+CORBA interface
+---------------
 
-AnsysS 17.0 to 2020 R1 - CORBA
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Ansys 17.0 supports the legacy CORBA interface, enabled with the
 ``ansys.mapdl.corba`` module. This interface allows you to send only
 text to and from the MAPDL service, relying on file IO for all other
 operations. While not as performant as gRPC, this interface still
 allows you to control a local instance of MAPDL. These versions of
-MAPDL support specific versions of Windows and Linux. For more information
-on the supported platforms, see 
+MAPDL support specific versions of Windows and Linux.
+For more information on the supported platforms, see 
 `Ansys Platform Support <ansys_platform_support_>`_.
 
-.. Note::
+The CORBA interface is likely to be phased out from MAPDL at some
+point. The gRPC interface is faster, more stable, and can run in
+both local and remote connection configurations.
 
-   The CORBA interface is likely to be phased out from MAPDL at some
-   point. The gRPC interface is faster, more stable, and can run in
-   both local and remote connection configurations.
 
+Console Interface
+-----------------
 
-Earlier than Ansys 17.0
-~~~~~~~~~~~~~~~~~~~~~~~
-The ``PyMAPDL`` project supports Ansys versions as early as 13.0 on Linux using a
+``PyMAPDL`` project supports Ansys versions as early as 13.0 on Linux using a
 console interface. Like CORBA, the console interface allows for the exchange of text to
 and from the Ansys instance.
 
-.. Warning::
+Because console-specific support is to be depreciated at some point, you should
+shift to a modern version of Ansys to continue to use PyMAPDL.
+
+
+
+.. _table_versions:
+
+**Table of supported versions**
+
++---------------------------+------------------------+-----------------------------------------------------------------------+
+| Ansys Version             | Recommended interface  | Support                                                               |
+|                           |                        +-----------------------+-----------------------+-----------------------+
+|                           |                        | gRPC                  | CORBA                 | Console (Only Linux)  |
++===========================+========================+=======================+=======================+=======================+
+| Ansys 2023 R1             | gRPC                   | |:heavy_check_mark:|  | |:heavy_minus_sign:|  | |:heavy_minus_sign:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2022 R2             | gRPC                   | |:heavy_check_mark:|  | |:heavy_minus_sign:|  | |:heavy_minus_sign:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2022 R1             | gRPC                   | |:heavy_check_mark:|  | |:heavy_minus_sign:|  | |:heavy_minus_sign:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2021 R2             | gRPC                   | |:heavy_check_mark:|  | |:heavy_check_mark:|  | |:heavy_minus_sign:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2021 R1             | gRPC                   | |:heavy_check_mark:|  | |:heavy_check_mark:|  | |:heavy_minus_sign:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2020 R2             | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2020 R1             | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2019 R3             | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2019 R2             | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 2019 R1             | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 19.2                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 19.1                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 19.0                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 18.2                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 18.1                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 18.0                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 17.2                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 17.1                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 17.0                | CORBA                  | |:x:|                 | |:heavy_check_mark:|  | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Ansys 16.2                | Console                | |:x:|                 | |:x:|                 | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+| Older up to Ansys 13.0    | Console                | |:x:|                 | |:x:|                 | |:heavy_check_mark:|  |
++---------------------------+------------------------+-----------------------+-----------------------+-----------------------+
+
+The following table shows the supported versions of Ansys and the recommended interface for each one of them in PyMAPDL.
 
-   Because console-specific support is to be depreciated at some point, you should
-   shift to a modern version of Ansys to continue to use PyMAPDL.
+* |:heavy_check_mark:| means that the interface is supported and recommended.
+* |:heavy_minus_sign:| means that the interface is supported, but not recommended. Their support might be dropped in the future.
+* |:x:| means that the interface is not supported.

doc/source/troubleshoot/index.rst

@@ -13,3 +13,15 @@ some of the most common problems and frequently asked questions are posted here.
 
    troubleshoot
    faq
+
+
+
+More help needed?
+-----------------
+
+  *"My problem is not listed here. What should I do?"*  
+
+You can go to `PyMAPDL Repository Discussion <pymapdl_discussions_>`_ and ask about it.
+
+If you think you found out a bug or you would like to do a feature request you can do so by
+opening an issue in `PyMAPDL Repository Issues <pymapdl_issues_>`_.