DOC: add more examples and automate their rendering (#109)

Author: jorgepiloto

.flake8

@@ -1,4 +1,4 @@
 [flake8]
 max-line-length = 88
 ignore = E501
-extend-ignore = E203
+extend-ignore = E203, W503

.gitignore

@@ -162,5 +162,5 @@ cython_debug/
 
 # End of https://www.toptal.com/developers/gitignore/api/python
 
-# Ignore baked output cookies from debugging
-output/
+# Ignore rendered examples
+*-rendered-example.yml

doc-style/action.yml

@@ -10,6 +10,7 @@ inputs:
   token:
     description: "Required token for Vale commenter."
     required: true
+    type: string
 
 runs:
   using: "composite"

doc/Makefile

@@ -19,6 +19,10 @@ help:
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+clean:
+	rm -rf $(BUILDDIR)
+	rm -rf $(SOURCEDIR)/**/*-rendered-example.yml
+
 # Customized pdf fov svg format images
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/build-actions/examples/build-ci-wheels-basic.yml

@@ -0,0 +1,9 @@
+build-c-extension:
+  name: "Build a C-extension library"
+  runs-on: ${{ '{{ matrix.os }}' }}
+  strategy:
+     matrix:
+         os: [ubuntu-latest, windows-latest, macos-11]
+  steps:
+    - name: "Build a C-extension library wheel artifacts"
+      uses: pyansys/actions/build-ci-library@{{ branch }}

doc/source/build-actions/examples/build-library-basic.yml

@@ -0,0 +1,8 @@
+build-library:
+  name: "Build library basic example"
+  runs-on: ubuntu-latest
+  steps:
+    - name: "Build library source and wheel artifacts"
+      uses: pyansys/actions/build-library@{{ branch }}
+      with:
+        library-name: "ansys-<product>-<library>"

doc/source/build-actions/examples/build-wheelhouse-basic.yml

@@ -0,0 +1,15 @@
+build-wheelhouse:
+  name: "Build wheelhouse for latest Python versions"
+  runs-on: ${{ '{{ matrix.os }}' }}
+  strategy:
+     matrix:
+         os: [ubuntu-latest, windows-latest]
+         python-version: ['3.7', '3.8', '3.9', '3.10']
+  steps:
+    - name: "Build a wheelhouse of the Python library"
+      uses: pyansys/actions/build-wheelhouse@{{ branch }}
+      with:
+        library-name: "<ansys-product-library>"
+        library-namespace: "<ansys.product.library>"
+        operating-system: ${{ '{{ matrix.os }}' }}
+        python-version: ${{ '{{ matrix.python-version }}' }}

doc/source/build-actions/index.rst

@@ -13,23 +13,19 @@ This action builds source and wheel artifacts for a Python library.
 
     {{ inputs_table }}
 
+    Examples
+    ++++++++
 
-Here is a code sample for using this action:
+    {% for filename, title in examples %}
+    .. dropdown:: {{ title }}
+       :animate: fade-in
 
-.. code-block:: yaml
+        .. literalinclude:: examples/{{ filename }}
+           :language: yaml
 
-    build-library:
-      name: Build library
-      runs-on: ubuntu-latest
-      steps:
-        - name: "Build library source and wheel artifacts"
-          uses: pyansys/actions/build-library@main
-          with:
-            library-name: "ansys-<product>-<library>"
+    {% endfor %}
 
 
-here is a code for using this action
-
 Build wheelhouse action
 -----------------------
 This action builds the wheelhouse for a Python library and publishes them as
@@ -39,25 +35,17 @@ artifacts.
 
     {{ inputs_table }}
 
-Here is a code sample for using this action:
+    Examples
+    ++++++++
+
+    {% for filename, title in examples %}
+    .. dropdown:: {{ title }}
+       :animate: fade-in
 
-.. code-block:: yaml
+        .. literalinclude:: examples/{{ filename }}
+           :language: yaml
 
-    build-wheelhouse:
-      name: Build the wheelhouse of the Python library
-      runs-on: ${{ matrix.os }}
-      strategy:
-         matrix:
-             os: [ubuntu-latest, windows-latest]
-             python-version: ['3.7', '3.8', '3.9', '3.10']
-      steps:
-        - name: "Build a wheelhouse of the Python library"
-          uses: pyansys/actions/build-wheelhouse@main
-          with:
-            library-name: "<ansys-product-library>"
-            library-namespace: "<ansys.product.library>"
-            operating-system: ${{ matrix.os }}
-            python-version: ${{ matrix.python-version }}
+    {% endfor %}
 
 
 Build C-extension library action
@@ -69,16 +57,15 @@ C-extension.
 
     {{ inputs_table }}
 
+    Examples
+    ++++++++
+
+    {% for filename, title in examples %}
+    .. dropdown:: {{ title }}
+       :animate: fade-in
 
-.. code-block:: yaml
+        .. literalinclude:: examples/{{ filename }}
+           :language: yaml
 
-    build-c-extension:
-      name: Build a C-extension library
-      runs-on: ${{ matrix.os }}
-      strategy:
-         matrix:
-             os: [ubuntu-latest, windows-latest, macos-11]
-      steps:
-        - name: "Build a C-extension library wheel artifacts"
-          uses: pyansys/actions/build-ci-library@main
+    {% endfor %}