docs: adding cheat sheet on documentation (#3422)

* docs: adding cheat sheet on documentation * chore: adding changelog file 3422.documentation.md * fix: trying to fix local errors * fix: adding `_static` folder * fix: add gitignore * docs: adding new section to cheat sheet * maint: trying to update ansys-sphinx-theme * maint: install poppler within cicd * test: install the dependency * feat: adding new cells in ``cheat_sheet`` - still WIP * fix: pool not supported in docs-build * fix: ``cheat_sheet`` * fix: ``cheat_sheet`` * fix: ``add_mesh`` * fix: trying to create a 1-page cheat sheet * docs: update ``cheat_sheet`` * fix: ``v24.2`` needs to be used as MAPDL version * docs: ``cheat_sheet`` * Apply suggestions from code review Co-authored-by: German <[email protected]> * review: applying changes requested by @germa89 * fix: ``prnsol`` * fix: using ``mapdl.clear()`` for performances * docs: removing ``eval`` for all plottings * Apply suggestions from code review * docs: removing previous PyMAPDL cheat sheet * docs: fixing link * fix: add jinja initial setup * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix: applying latest changes * Apply suggestions from code review Co-authored-by: Maxime Rey <[email protected]> * fix: attempt to fix the jinja error * fix: intersphinx link * fix: extensions * fix: cheat_sheet header * ci: auto fixes from pre-commit.com hooks. for more information, see https://pre-commit.ci * fix: pre-commit * docs: fix typo in doc * review: applying @germa89's suggestions --------- Co-authored-by: pyansys-ci-bot <[email protected]> Co-authored-by: Revathyvenugopal162 <[email protected]> Co-authored-by: Revathy Venugopal <[email protected]> Co-authored-by: German <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Maxime Rey <[email protected]>
ansys · Oct 3, 2024 · 1c825b6 · 1c825b6
1 parent 9d437e3
commit 1c825b6
Show file tree

Hide file tree

Showing 13 changed files with 332 additions and 22 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -40,9 +40,9 @@ 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_EXAMPLES_CACHE: 2
-  RESET_DOC_BUILD_CACHE: 2
-  RESET_AUTOSUMMARY_CACHE: 2
+  RESET_EXAMPLES_CACHE: 0
+  RESET_DOC_BUILD_CACHE: 0
+  RESET_AUTOSUMMARY_CACHE: 0
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -263,11 +263,28 @@ jobs:
 
       - name: "Install docs build requirements"
         run: |
+          pip uninstall ansys-sphinx-theme
           pip install .[doc]
 
       - name: "Waiting for the services to be up"
         run: |
           .ci/waiting_services.sh
+      
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          tinytex: true
+
+      - name: Check Quarto Version
+        shell: bash
+        run: |
+          quarto --version
+      
+      - name: "Install Poppler for PDF to PNG conversion"
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y poppler-utils
 
       - name: "Build documentation"
         run: |

diff --git a/README.md b/README.md
@@ -50,8 +50,7 @@ In the upper right corner of the documentation's title bar, there is an option f
 viewing the documentation for the latest stable release to viewing the documentation for the
 development version or previously released versions.
 
-You can also [view](https://cheatsheets.docs.pyansys.com/pymapdl_cheat_sheet.png) or
-[download](https://cheatsheets.docs.pyansys.com/pymapdl_cheat_sheet.pdf) the
+You can also [download](https://mapdl.docs.pyansys.com/version/stable/_static/cheat_sheet.pdf) the
 PyMAPDL cheat sheet. This one-page reference provides syntax rules and commands
 for using PyMAPDL. 
 

diff --git a/doc/changelog.d/3422.documentation.md b/doc/changelog.d/3422.documentation.md
@@ -0,0 +1 @@
+docs: adding cheat sheet on documentation
diff --git a/doc/source/cheat_sheet/.gitignore b/doc/source/cheat_sheet/.gitignore
@@ -0,0 +1 @@
+/.quarto/
diff --git a/doc/source/cheat_sheet/_static/README.md b/doc/source/cheat_sheet/_static/README.md
diff --git a/doc/source/cheat_sheet/cheat_sheet.qmd b/doc/source/cheat_sheet/cheat_sheet.qmd
@@ -0,0 +1,278 @@
+---
+title: PyMAPDL cheat sheet
+format: cheat_sheet-pdf
+params:
+  version: main
+footer: PyMAPDL
+footerlinks:
+  - urls: 'https://mapdl.docs.pyansys.com/version/stable/'
+    text: Documentation
+  - urls: 'https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html'
+    text: Getting started
+  - urls: 'https://mapdl.docs.pyansys.com/version/stable/examples.html'
+    text: Examples
+  - urls: 'https://mapdl.docs.pyansys.com/version/stable/api/index.html'
+    text: API reference
+  - urls: 'https://github.com/ansys/pymapdl/discussions'
+    text: Discussions
+  - urls: 'https://github.com/ansys/pmapdl/issues'
+    text: 'Issues'
+execute:
+  output: false
+  eval: true
+
+latex-clean: true
+latex-auto-install: true
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .qmd
+      format_name: quarto
+      format_version: '1.0'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+# Connect to MAPDL remote session
+
+Launch and connect to MAPDL. You can specify the version you want to use with
+``version`` argument.
+```{python}
+#| eval: false
+from ansys.mapdl.core import launch_mapdl
+mapdl = launch_mapdl(version=242)
+```
+
+Exit a session
+```{python}
+#| eval: false
+mapdl.exit()
+```
+
+Connect to an existing instance at IP address ``192.168.1.30`` and port ``50001``:
+```{python}
+#| eval: false
+mapdl = launch_mapdl(start_instance=False, ip='192.168.1.30', port=50001)
+```
+
+```{python}
+#| echo: false
+from ansys.mapdl.core import launch_mapdl
+mapdl = launch_mapdl()
+```
+
+Create and exit a pool of instances:
+```{python}
+#| eval: false
+# Create a pool of 10 instances
+from ansys.mapdl.core import pool
+mapdl_pool = pool.MapdlPool(10)
+# Exit the pool
+mapdl_pool.exit()
+```
+
+# PyMAPDL CLI
+
+Access MAPDL instances through CLI
+```{console}
+#| eval: false
+# Start an MAPDL instance at port ``50051``
+pymapdl start --port 50051
+# List the current MAPDL instances and processes
+pymapdl list
+# Stop all the MAPDL instances
+pymapdl stop --all
+```
+
+# PyMAPDL commands
+
+PyMAPDL commands are Python statements that act as a
+wrapper for APDL commands. For example: ``ESEL,s,type,1`` 
+is translated as
+```{python}
+#| echo: false
+mapdl.clear()
+```
+```{python}
+mapdl.esel('s', 'type', vmin=1)
+```
+
+Help for the MAPDL class functions is accessible with:
+```{python}
+help(mapdl.esel)
+```
+
+Most of the time, commands that start with \* or \/ have these characters
+removed:
+```{python}
+#| eval: false
+mapdl.prep7() # /PREP7
+mapdl.get() # *GET
+```
+
+Load arrays from Python to MAPDL:
+```{python}
+#| echo: false
+mapdl.clear()
+```
+```{python}
+import numpy as np
+np_array = np.array([[1,2,3], [4,5,6]])
+mapdl.load_array("array_name", np_array)
+```
+
+Write parameters and access from or to the MAPDL database:
+```{python}
+# Create a parameter from a NumPy array
+mapdl.parameters['my_np_param'] = np_array
+# Save a parameter to a NumPy array
+saved_np_array = mapdl.parameters['my_np_param']
+```
+
+Access to specific model entity values with ``get_array`` and 
+`` get_value``.
+```{python}
+# List the current selected node numbers
+mapdl.get_array('NODE', item1='NLIST')
+# Get the number of selected nodes
+total_node = mapdl.get_value(entity='node', item1='count')
+```
+
+# Convert APDL script to Python files
+
+An existing APDL script can be converted to PyMAPDL format
+with the following commands:
+```{python}
+#| eval: false
+import ansys.mapdl.core as pymapdl
+pymapdl.convert_script(
+  "mapdl_script.dat", "pymapdl_script.py"
+)
+```
+
+# Mesh and geometry of a model
+
+Store the finite element mesh as a 
+[VTK UnstructuredGrid data](https://vtk.org/doc/nightly/html/classvtkUnstructuredGrid.html)
+object:
+
+```{python}
+#| echo: false
+#####################################################################
+# Hidden example for testing purpose (3d_plate_thermal.py)
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+mapdl.clear()
+
+# Create a simple beam, specify the material properties, and mesh it.
+mapdl.prep7()
+mapdl.mp("kxx", 1, 45)
+mapdl.et(1, 90)
+mapdl.block(-0.3, 0.3, -0.46, 1.34, -0.2, -0.2 + 0.02)
+mapdl.vsweep(1)
+
+# Set the thermal boundary conditions
+mapdl.asel("S", vmin=3)
+mapdl.nsla()
+mapdl.d("all", "temp", 5)
+mapdl.asel("S", vmin=4)
+mapdl.nsla()
+mapdl.d("all", "temp", 100)
+out = mapdl.allsel()
+
+mapdl.vsweep(1)
+```
+
+```{python}
+grid = mapdl.mesh.grid
+```
+
+Save element and node numbers to Python arrays with
+the ``mapdl.mesh`` and the ``mapdl.geometry`` classes.
+
+
+```{python}
+# Get an array of the nodal coordinates
+nodes = mapdl.mesh.nodes
+# Save node numbers of selected nodes to an array
+node_num = mapdl.mesh.nnum
+# Save volume numbers of selected nodes to an array
+volum_numbers = mapdl.geometry.vnum
+# Save keypoint numbers of selected nodes to an array
+keypoints = mapdl.geometry.keypoints
+```
+
+# Solve an analysis
+
+```{python}
+mapdl.solution()
+mapdl.solve()
+mapdl.finish()
+```
+
+# Post-process results
+
+The
+[PostProcessing](https://mapdl.docs.pyansys.com/version/stable/api/_autosummary/ansys.mapdl.core.post.PostProcessing.html#ansys.mapdl.core.post.PostProcessing)
+class is used for plotting and saving results to NumPy arrays.
+
+```{python}
+mapdl.post1()
+mapdl.set(1, 1)
+mapdl.allsel()
+
+# Plot nodal temperatures
+mapdl.post_processing.plot_nodal_temperature()
+# Save nodal temperatures to a Python array
+nodal_temp= mapdl.post_processing.nodal_temperature()
+```
+
+You can store the command output following the 
+[Postprocessing object methods](https://mapdl.docs.pyansys.com/version/stable/user_guide/post.html#postprocessing-object-methods):
+```{python}
+cmd = mapdl.prnsol("TEMP")
+cmd.to_list()
+```
+
+# Create nice plots
+
+Use [PyVista](https://docs.pyvista.org/) to interpolate data, save results
+and store them in the underlying
+[UnstructuredGrid](https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid#)
+object:
+
+```{python}
+from pyvista import Plotter
+pl = Plotter()
+pm = mapdl.post_processing.plot_element_stress(
+  "X", return_plotter=True
+)
+pl.add_mesh(pm.meshes[0])
+pl.show()
+```
+
+```{python}
+#| eval: false
+# Plot selected elements
+mapdl.eplot()
+# Plot selected volumes
+mapdl.vplot()
+# Plot selected areas
+mapdl.aplot()
+# Plot selected lines
+mapdl.lplot()
+```
+
+```{python}
+#| eval: false
+# Testing one of the above plotting
+mapdl.eplot()
+```
+
+```{python}
+#| echo: false
+mapdl.exit()
+```
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -11,11 +11,15 @@
 import numpy as np
 import pyvista
 from sphinx.application import Sphinx
+from sphinx.util import logging
 from sphinx_gallery.sorting import FileNameSortKey
 
 from ansys.mapdl import core as pymapdl
 from ansys.mapdl.core import __version__
 
+# Convert notebooks into Python scripts and include them in the output files
+logger = logging.getLogger(__name__)
+
 viz_interface.DOCUMENTATION_BUILD = True
 pyvista.BUILDING_GALLERY = True
 pyvista.OFF_SCREEN = True
@@ -93,6 +97,7 @@
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinx_design",
+    "sphinx_jinja",
     "sphinx_copybutton",
     "sphinx_gallery.gen_gallery",
     "sphinxemoji.sphinxemoji",
@@ -107,7 +112,7 @@
     "numpy": ("https://numpy.org/doc/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
-    "pyvista": ("https://docs.pyvista.org/version/stable/", None),
+    "pyvista": ("https://docs.pyvista.org", None),
     "grpc": ("https://grpc.github.io/grpc/python/", None),
     "pypim": ("https://pypim.docs.pyansys.com/version/dev/", None),
     "ansys-dpf-core": ("https://dpf.docs.pyansys.com/version/stable/", None),
@@ -306,11 +311,11 @@
         "json_url": f"https://{cname}/versions.json",
         "version_match": switcher_version,
     },
-    "use_meilisearch": {
-        "api_key": os.getenv("MEILISEARCH_PUBLIC_API_KEY", ""),
-        "index_uids": {
-            f"pymapdl-v{switcher_version.replace('.', '-')}": "PyMAPDL",
-        },
+    "cheatsheet": {
+        "file": "cheat_sheet/cheat_sheet.qmd",
+        "title": "PyMAPDL cheat sheet",
+        "version": f"v{version}",
+        "pages": ["getting_started/learning"],
     },
 }
 
@@ -429,3 +434,8 @@ def setup(app: Sphinx):
     from helpers import HideObject
 
     app.add_directive("hideobject", HideObject)
+
+
+jinja_contexts = {
+    "cheat_sheet": {"version": switcher_version},
+}
diff --git a/doc/source/getting_started/Cheat_Sheet_PyMAPDL.pdf b/doc/source/getting_started/Cheat_Sheet_PyMAPDL.pdf