feat: add quarto cheat sheet setup to docs build actions

.github/workflows/ci_cd.yml

@@ -132,6 +132,7 @@ jobs:
           skip-install: true
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
           use-python-cache: false
+          needs-quarto: true
 
   tests:
     name: "Tests"

.gitignore

@@ -75,6 +75,7 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+doc/source/cheat_sheet.qmd
 
 # PyBuilder
 .pybuilder/

_doc-build-linux/action.yml

@@ -119,6 +119,14 @@ inputs:
     required: true
     type: boolean
 
+  needs-quarto:
+    description: |
+      Whether to add a Quarto cheatsheet to the documentation. Default value is
+      ``false``.
+    default: false
+    required: false
+    type: boolean
+
 
 runs:
   using: "composite"
@@ -155,6 +163,24 @@ runs:
       run: |
         sudo apt-get install -y texlive-latex-extra latexmk
 
+    - name: Install Quarto
+      if: ${{ inputs.needs-quarto == 'true' }}
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        tinytex: true
+
+    - name: Check Quarto Version
+      if: ${{ inputs.needs-quarto == 'true' }}
+      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: "Check if requirements.txt file exists"
       shell: bash
       run: |

_doc-build-windows/action.yml

@@ -111,6 +111,14 @@ inputs:
     required: true
     type: boolean
 
+  needs-quarto:
+    description: |
+      Whether to add a Quarto cheatsheet to the documentation. Default value is
+      ``false``.
+    default: false
+    required: false
+    type: boolean
+
 
 runs:
   using: "composite"
@@ -164,6 +172,12 @@ runs:
         choco install miktex -y
         echo "C:\Program Files\MiKTeX\miktex\bin\x64" | Out-File -Append -FilePath $env:GITHUB_PATH -Encoding utf8
 
+    - name: "Install Poppler for PDF to PNG conversion"
+      shell: powershell
+      run: |
+        choco install poppler -y
+        echo "C:\Program Files\poppler\bin" | Out-File -Append -FilePath $env:GITHUB_PATH -Encoding utf8
+
     # ------------------------------------------------------------------------
 
     - uses: ansys/actions/_logging@main
@@ -179,6 +193,26 @@ runs:
 
     # ------------------------------------------------------------------------
 
+    - uses : ansys/actions/_logging@main
+      with:
+        level: "INFO"
+        message: >
+          Setup quarto to build the cheatsheet.
+
+    - name: Install Quarto
+      if: ${{ inputs.needs-quarto == 'true' }}
+      uses: quarto-dev/quarto-actions/setup@v2
+      with:
+        tinytex: true
+
+    - name: Check Quarto Version
+      if: ${{ inputs.needs-quarto == 'true' }}
+      shell: bash
+      run: |
+        quarto --version
+
+    # ------------------------------------------------------------------------
+
     - uses: ansys/actions/_logging@main
       with:
         level: "INFO"

doc-build/action.yml

@@ -167,6 +167,13 @@ inputs:
     required: false
     type: boolean
 
+  needs-quarto:
+    description: >
+      Whether to add a Quarto cheatsheet to the documentation. Default value is
+      ``false``.
+    default: false
+    required: false
+    type: boolean
 
 runs:
   using: "composite"
@@ -199,6 +206,7 @@ runs:
         skip-json-build: ${{ inputs.skip-json-build }}
         check-links: ${{ inputs.check-links }}
         add-pdf-html-docs-as-assets: ${{ inputs.add-pdf-html-docs-as-assets }}
+        needs-quarto: ${{ inputs.needs-quarto }}
 
     # ------------------------------------------------------------------------
 
@@ -222,3 +230,4 @@ runs:
         skip-json-build: ${{ inputs.skip-json-build }}
         check-links: ${{ inputs.check-links }}
         add-pdf-html-docs-as-assets: ${{ inputs.add-pdf-html-docs-as-assets }}
+        needs-quarto: ${{ inputs.needs-quarto }}

doc/source/.gitignore

@@ -0,0 +1 @@
+/.quarto/

doc/source/cheat_sheet.jinja

@@ -0,0 +1,43 @@
+---
+title: Ansys Actions
+format: cheat_sheet-pdf
+version: {{ version }}
+footer: Getting started with Ansys Actions
+footerlinks:
+  - urls: 'https://actions.docs.ansys.com/version/stable/'
+    text: Ansys Actions documentation
+  - urls: 'https://github.com/ansys/actions/'
+    text: Ansys Actions GitHub
+execute:
+    # output: false
+    eval: false
+
+latex-clean: 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
+---
+{%- for action_name, action_data in actions.items() %}
+# {{ action_name | capitalize }}
+{% for example in action_data.examples_for_cheatsheet %}
+
+**{{ example.title | capitalize }}**
+
+```{yml}
+{{ example.code }}
+```
+
+{% if example.reference_url -%}
+***Ref***: [{{ example.title }}]({{ example.reference_url }})
+{% endif -%}
+{% endfor -%}
+
+{% endfor -%}

doc/source/conf.py

@@ -24,7 +24,7 @@
 project = "Ansys Actions"
 copyright = f"(c) 2022-{datetime.today().year} ANSYS, Inc. and/or its affiliates."
 author = "ANSYS, Inc."
-cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
+cname = os.getenv("DOCUMENTATION_CNAME", "actions.docs.ansys.com")
 
 # Read version from VERSION file in base root directory
 source_dir = pathlib.Path(__file__).parent.resolve().absolute()
@@ -40,6 +40,7 @@
 actions_version = (
     "main" if __version__.endswith("dev0") else f"v{get_version_match(__version__)}"
 )
+switcher_version = get_version_match(__version__)
 
 html_theme = "ansys_sphinx_theme"
 html_favicon = ansys_favicon
@@ -63,14 +64,18 @@
     ],
     "switcher": {
         "json_url": f"https://{cname}/versions.json",
-        "version_match": get_version_match(__version__),
+        "version_match": switcher_version,
     },
     "use_meilisearch": {
         "api_key": os.getenv("MEILISEARCH_PUBLIC_API_KEY", ""),
         "index_uids": {
-            f"actions-v{get_version_match(__version__).replace('.', '-')}": "Ansys-actions",
+            f"actions-v{switcher_version.replace('.', '-')}": "Ansys-actions",
         },
     },
+    "cheatsheet": {
+        "file": "cheat_sheet.qmd",
+        "title": "Actions cheat sheet",
+    },
 }
 
 # Specify Sphinx extensions to use
@@ -338,3 +343,55 @@ def load_file_lines_as_list(file_path):
 jinja_contexts["check-vulnerabilities"]["ignored_safety"] = load_file_lines_as_list(
     IGNORED_SAFETY
 )
+
+
+def get_example_content_for_cheatsheet(example_file):
+    """Get the content of an example file for the cheatsheet.
+
+    Parameters
+    ----------
+    example_file : ~pathlib.Path
+        The ``Path`` for the example file.
+
+    Returns
+    -------
+    str
+        A string representing the content of the example file.
+    """
+    with open(example_file, "r") as yaml_file:
+        file_content = yaml.safe_load(yaml_file)
+        first_key = next(iter(file_content))
+        file_content = file_content[first_key]["steps"]
+        return yaml.dump(file_content, default_flow_style=False)
+
+
+def get_docs_link_for_action(action_file, action_name):
+    """Get the link to the documentation for a specific action."""
+    return f"https://{cname}/version/{switcher_version}/{action_file.parent.parent.name}/index.html#{action_name}-action"
+
+
+# Generate the cheatsheet content
+actions_cheatsheet_jinja_contexts = {
+    action_dir.name.replace("-", " ").casefold(): {
+        "examples_for_cheatsheet": [
+            {
+                "name": action_dir.name.replace("-", " "),
+                "title": get_example_file_title(file),
+                "code": get_example_content_for_cheatsheet(file),
+                "reference_url": get_docs_link_for_action(file, action_dir.name),
+            }
+            for file in collect_examples_from_action_name(action_dir.name)
+        ]
+    }
+    for action_dir in public_actions
+}
+
+jinja2_env = jinja2.Environment(loader=jinja2.FileSystemLoader(source_dir))
+template = jinja2_env.get_template("cheat_sheet.jinja")
+
+content = template.render(
+    version=actions_version, actions=actions_cheatsheet_jinja_contexts
+)
+with open("cheat_sheet.qmd", "w") as cheat_sheet_file_rendered:
+    cheat_sheet_file_rendered.write(content)
+    cheat_sheet_file_rendered.close()

requirements/requirements_doc.txt

@@ -1,4 +1,6 @@
 ansys-sphinx-theme==1.0.7
+jupyter==1.0.0
+nbformat==5.10.4
 pyyaml==6.0.2
 Sphinx==8.0.2
 sphinx-copybutton==0.5.2