docs: adding cheat sheet on documentation

.github/workflows/ci.yml

@@ -267,6 +267,16 @@ jobs:
       - 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: "Build documentation"
         run: |

doc/source/cheat_sheet/cheat_sheet.qmd

@@ -0,0 +1,126 @@
+---
+title: Your title here
+format: cheat_sheet-pdf
+version: Your version here
+footer: Your footer here
+footerlinks:
+  - urls: Your URL here
+    text: Your text here
+  - urls: Your URL here
+    text: Your text here
+# Uncomment the following line to not evaluate code cells
+# execute:
+#     eval: false # Set to true to evaluate code cells
+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
+---
+
+# General section
+
+Description of the first section goes here.
+
+```{python}
+import os
+```
+
+# Section with code output
+
+Description of the second section goes here.
+
+```{python}
+print("Hello, world!")
+```
+
+# Section with code evaluation but no results included
+
+This section is evaluated but execution results are not included in the output.
+```{python}
+#| output: false
+print("Hello, world!")
+```
+
+# Section with code evaluation but no results included
+
+This section is evaluated but execution results are not included in the output.
+
+```{python}
+#| output: false
+print(os.getcwd())
+```
+
+# Section with code evaluation and results included
+
+This section is evaluated and execution results are included in the output.
+
+```{python}
+print(os.getcwd())
+```
+
+# Section without code evaluation
+```{python}
+#| eval: false
+print(os.getcwd())
+```
+
+If there is no evaluation, the code cell is not executed.
+Thus, no execution results are included in the output.
+
+# Section without code echo
+
+This section is not evaluated, and the code cell is not shown in
+the rendered document. However, the output is included in the
+rendered document.
+
+```{python}
+#| echo: false
+print("Hello, world!")
+```
+
+# Section without code echo and output
+This section is not evaluated, and the code cell is not shown in
+the rendered document. The output is also not included in the
+rendered document.
+
+```{python}
+#| echo: false
+#| output: false
+print("Hello, world!")
+```
+
+# Use of variables
+
+## Styles of text
+
+**Bold text**
+
+*Italic text*
+
+***Bold and italic text***
+
+## Lists and images
+1. Numbered list
+2. Numbered list
+3. Numbered list
+
+- Bulleted list
+- Bulleted list
+- Bulleted list
+
+## Subsection
+
+- Add subsections as needed.
+- Add more subsections as needed.
+- Add more subsections as needed.
+
+- [link](https://www.google.com)
+- [link](https://www.google.com)
+- [link](https://www.google.com)

doc/source/conf.py

@@ -9,12 +9,17 @@
 from ansys_sphinx_theme import ansys_favicon, get_version_match
 import numpy as np
 import pyvista
+import sphinx
 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
@@ -308,6 +313,10 @@
             f"pymapdl-v{switcher_version.replace('.', '-')}": "PyMAPDL",
         },
     },
+    "cheatsheet": {
+        "file": "cheat_sheet/cheat_sheet.qmd",
+        "title": "PyMAPDL cheat sheet",
+    },
 }
 
 html_context = {
@@ -420,3 +429,32 @@ def setup(app: Sphinx):
 
     # Julia lexer
     app.add_lexer("julia", JuliaLexer)
+
+
+# -- Configurations for PyMAPDL cheat seet -----------------------------------
+
+
+def replace_version_in_qmd(file_path: Path, search, replace):
+    """Update the version in cheatsheet."""
+    with file_path.open("r") as file:
+        content = file.read()
+
+    logger.info(f"replace_version_in_qmd: replacing {search} with {replace}")
+    content = content.replace(f"version: {search}", f"version: {replace}")
+
+    with file_path.open("w") as file:
+        file.write(content)
+
+
+def update_qmd_mod(app: sphinx.application.Sphinx):
+    """Update the version in cheatsheet."""
+    cheathseet_path = Path(__file__).parent / "cheatsheet" / "cheat_sheet.qmd"
+    logger.info(f"Changing {cheathseet_path}")
+    replace_version_in_qmd(cheathseet_path, "main", version)
+
+
+def revert_qmd_mod(app: sphinx.application.Sphinx, exception):
+    """Revert the version in cheatsheet that was modified."""
+    cheathseet_path = Path(__file__).parent / "cheatsheet" / "cheat_sheet.qmd"
+    logger.info(f"Reverting {cheathseet_path}")
+    replace_version_in_qmd(cheathseet_path, version, "main")

pyproject.toml

@@ -76,21 +76,23 @@ doc = [
     "ansys-dpf-core==0.10.1",
     "ansys-mapdl-reader==0.54.1",
     "ansys-tools-visualization-interface==0.4.4",
-    "ansys-sphinx-theme==1.0.11",
+    "ansys-sphinx-theme@git+https://github.com/ansys/ansys-sphinx-theme.git@fix/test-cheatsheet",
     "grpcio==1.66.1",
     "imageio-ffmpeg==0.5.1",
     "imageio==2.35.1",
+    "jupyter==1.1.1",
     "jupyter_sphinx==0.5.3",
     "jupyterlab>=3.2.8",
     "matplotlib==3.9.2",
+    "nbformat==5.10.4",
     "numpydoc==1.8.0",
     "pandas==2.2.2",
     "plotly==5.24.1",
     "pyiges[full]==0.3.1",
     "pypandoc==1.13",
     "pytest-sphinx==0.6.3",
     "pythreejs==2.4.2",
-    "sphinx-autobuild==2024.9.19",
+    "sphinx-autobuild==2024.9.3",
     "sphinx-autodoc-typehints==1.25.2",
     "sphinx-copybutton==0.5.2",
     "sphinx-design==0.6.1",