Add examples of extension libraries.

.github/workflows/ci_cd.yml

@@ -49,7 +49,7 @@ jobs:
 
   doc-deploy-development:
     name: Doc dev version deploy
-    if: ${{ github.ref == 'refs/heads/main' }}
+    # if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
     needs: doc-build
     steps:

doc/source/conf.py

@@ -2,7 +2,11 @@
 
 from datetime import datetime
 import os
+from pathlib import Path
+from typing import List
 
+from bs4 import BeautifulSoup
+import requests
 from sphinx.builders.latex import LaTeXBuilder
 
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
@@ -19,6 +23,10 @@
     watermark,
 )
 
+THIS_PATH = Path(__file__).parent.resolve()
+
+EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
+
 # Project information
 project = "ansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -66,6 +74,8 @@
     "sphinx.ext.intersphinx",
     "notfound.extension",
     "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_jinja",
 ]
 
 # Intersphinx mapping
@@ -128,3 +138,73 @@
     "body": generate_404(),
 }
 notfound_no_urls_prefix = True
+
+
+def extract_example_links(archive_url: str) -> List[str]:
+    """
+    Extract example links from a specific URL.
+
+    Parameters
+    ----------
+    archive_url : str
+        The URL of the archive to retrieve the example links from.
+
+    Returns
+    -------
+    list
+        List of example links.
+    """
+    response = requests.get(archive_url)
+    soup = BeautifulSoup(response.content, "html5lib")
+    links = soup.find_all("a")
+    exclude_files = ["article-info.txt"]
+    example_links = [
+        f"https://raw.githubusercontent.com{link['href'].replace('/blob/', '/')}"
+        for link in links
+        if link["href"].endswith(".txt") and all(file not in link["href"] for file in exclude_files)
+    ]
+    return example_links
+
+
+def download_and_process_files(example_links: List[str]) -> List[str]:
+    """Download and process a series of example files.
+
+    This function downloads a series of example files using a
+    list of links and processes each file.
+
+    Parameters
+    ----------
+    example_links : List[str]
+        List of links to the example files to be downloaded.
+
+    Returns
+    -------
+    list
+        List of the names of the processed files.
+    """
+    file_names = []
+    for link in example_links:
+        file_name = link.split("/")[-1]
+        file_path = str((EXAMPLE_PATH / file_name).absolute())
+        with open(file_path, "wb") as f:
+            response = requests.get(link)
+            content = response.content.decode()
+            lines = content.splitlines()
+            # Customised only to remove the warnings on docs build.
+            filtered_lines = [
+                line
+                for line in lines
+                if not line.startswith("Cards Clickable") and not line.startswith("...............")
+            ]
+            f.write(
+                b"\n".join([line.replace("target", file_name).encode() for line in filtered_lines])
+            )
+        file_names.append(file_name)
+    return file_names
+
+
+URL_ARCHIVE = "https://github.com/executablebooks/sphinx-design/tree/main/docs/snippets/rst"
+example_links = extract_example_links(URL_ARCHIVE)
+file_names = download_and_process_files(example_links)
+
+jinja_contexts = {"examples": {"inputs_examples": file_names}}

doc/source/examples/index.rst

@@ -0,0 +1,28 @@
+========
+Examples
+========
+This show how the different extensions get rendered in ansys-sphinx-theme. This is for testing purpose.
+
+.. grid:: 2
+
+   .. grid-item::
+      .. card:: Sphinx design
+         :link: sphinx-design
+         :link-type: ref
+
+            Examples rendered with sphinx design.
+
+   .. grid-item::
+      .. card:: Table
+         :link: table
+         :link-type: ref
+
+            Examples for table with js and rst.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   sphinx-design
+   table

doc/source/examples/snippet.py

@@ -0,0 +1,33 @@
+"""Sample functions for ansys-sphinx-theme."""
+
+
+def func(arg1, arg2):
+    """Summary line <should be one one line>.
+
+    Extended description of function.  Can span multiple lines and
+    provides a general overview of the function.
+
+    .. warning::
+       Use the ``.. warning::`` directive within the doc-string for any
+       warnings you would like to explicitly state.  For example, if
+       this method will be deprecated in the next release.
+
+    Parameters
+    ----------
+    arg1 : int
+        Description of arg1.
+    arg2 : str
+        Description of arg2.
+
+    Returns
+    -------
+    bool
+        Description of return value.
+
+    Examples
+    --------
+    >>> func(1, 'foo')
+    True
+
+    """
+    return True

doc/source/examples/sphinx-design.rst

@@ -0,0 +1,23 @@
+.. _sphinx-design:
+
+Sphinx design
+=============
+The rendering of sphinx design with ansys sphinx theme. To use this see 
+the full document of `sphinx design <https://sphinx-design.readthedocs.io/en/latest/index.html>`_.
+
+.. jinja:: examples
+
+    {% for filename in inputs_examples %}
+    {% set title = filename.split('.')[0] %}
+
+    {{ title[0].upper() }}{{ title[1:] }}
+    {{ '~' * (title | length) }}
+
+        .. literalinclude:: sphinx_examples/{{ filename }}
+           :language: rst
+
+    This directive renders the as follow:
+
+        .. include:: sphinx_examples/{{ filename }}
+
+    {% endfor %}

doc/source/examples/sphinx_examples/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

doc/source/examples/table.rst

@@ -0,0 +1,99 @@
+.. _table:
+
+Table
+=====
+The rendering of table directive with ansys sphinx theme.
+
+Data table
+----------
+Here is the data table.
+
+.. code:: rst
+
+    .. table::
+        :class: datatable
+
+        =====  =====  =======
+        A      B      A and B
+        =====  =====  =======
+        False  False  False
+        True   False  False
+        False  True   False
+        True   True   True
+        =====  =====  =======
+
+.. table::
+    :class: datatable
+
+    =====  =====  =======
+    A      B      A and B
+    =====  =====  =======
+    False  False  False
+    True   False  False
+    False  True   False
+    True   True   True
+    =====  =====  =======
+
+Longtable-centered
+------------------
+Here is the long table. 
+
+.. code:: rst
+
+    .. table:: 
+        :class: longtable-centered
+
+        +---------------------------+-------------------+
+        |                           | MAPDL Command     |
+        +===========================+===================+
+        | **GUI commands**          | * ``*ASK``        |
+        |                           |                   |
+        | **GUI commands**          | * ``*ASK``        |
+        |                           |                   |
+        | **GUI commands**          | * ``*ASK``        |
+        +---------------------------+-------------------+
+
+.. table:: 
+   :class: longtable-centered
+
+   +---------------------------+-------------------+
+   |                           | MAPDL Command     |
+   +===========================+===================+
+   | **GUI commands**          | * ``*ASK``        |
+   |                           |                   |
+   | **GUI commands**          | * ``*ASK``        |
+   |                           |                   |
+   | **GUI commands**          | * ``*ASK``        |
+   +---------------------------+-------------------+
+
+Table-centered
+--------------
+Here is the table centered.
+
+.. code:: rst
+
+    .. table:: 
+        :class: table-centered
+
+        +---------------------------+-------------------+
+        |                           | MAPDL Command     |
+        +===========================+===================+
+        | **GUI commands**          | * ``*ASK``        |
+        +---------------------------+-------------------+
+        | **GUI commands**          | * ``*ASK``        |
+        +---------------------------+-------------------+
+        | **GUI commands**          | * ``*ASK``        |
+        +---------------------------+-------------------+
+
+.. table::
+    :class: table-centered
+
+    +---------------------------+-------------------+
+    |                           | MAPDL Command     |
+    +===========================+===================+
+    | **GUI commands**          | * ``*ASK``        |
+    +---------------------------+-------------------+
+    | **GUI commands**          | * ``*ASK``        |
+    +---------------------------+-------------------+
+    | **GUI commands**          | * ``*ASK``        |
+    +---------------------------+-------------------+

doc/source/getting_started/index.rst

@@ -32,5 +32,3 @@ Consider using the ``conf.py`` for this repository:
 .. toctree::
    :hidden:
    :maxdepth: 2
-
-

doc/source/index.rst

@@ -10,3 +10,4 @@ Ansys Sphinx Theme documentation |version|
 
    getting_started/index.rst
    user_guide/index.rst
+   examples/index.rst

pyproject.toml

@@ -36,6 +36,11 @@ doc = [
     "Sphinx==5.3.0",
     "sphinx-copybutton==0.5.1",
     "sphinx-notfound-page==0.8.3",
+    "sphinx-design==0.3.0",
+    "bs4==0.0.1",
+    "html5lib",
+    "requests==2.28.2",
+    "sphinx-jinja==2.0.2",
 ]
 
 [project.entry-points."sphinx.html_themes"]

src/ansys_sphinx_theme/__init__.py

@@ -14,8 +14,10 @@
 THEME_PATH = THIS_PATH / "theme" / "ansys_sphinx_theme"
 STATIC_PATH = THEME_PATH / "static"
 STYLE_PATH = STATIC_PATH / "css"
+JS_PATH = STATIC_PATH / "js"
 CSS_PATH = STYLE_PATH / "ansys_sphinx_theme.css"
 TEMPLATES_PATH = THEME_PATH / "_templates"
+JS_FILE = JS_PATH / "table.js"
 
 # make logo paths available
 ansys_favicon = str((STATIC_PATH / "ansys-favicon.png").absolute())
@@ -108,6 +110,7 @@ def setup(app: sphinx.application.Sphinx) -> Dict:
     if not CSS_PATH.exists():
         raise FileNotFoundError(f"Unable to locate ansys-sphinx theme at {CSS_PATH.absolute()}")
     app.add_css_file(str(CSS_PATH.relative_to(STATIC_PATH)))
+    app.add_js_file(str(JS_FILE.relative_to(STATIC_PATH)))
 
     # Add templates for autosummary
     app.config.templates_path.append(str(TEMPLATES_PATH))

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/css/ansys_sphinx_theme.css

@@ -93,8 +93,9 @@ html[data-theme="light"] {
   --pst-color-target: rgb(255, 255, 255);
   /* color for sphinx-gallery-code output*/
   --pst-color-codecell: #fafae2;
-  --pst-color-codeout:var(--pst-color-inline-code);
-  --pst-color-sig:#0965C8;
+  --pst-color-codeout: var(--pst-color-inline-code);
+  --pst-color-sig: #0965C8;
+  --sd-color-primary : var(--pst-color-text-base)
 }
 
 html[data-theme="dark"] {
@@ -296,6 +297,7 @@ Sphinx-design
 
 .bd-content .sd-tab-set>input:checked+label, .bd-content .sd-tab-set>input:not(:checked)+label:hover {
   color: var(--pst-color-text-base);
+  border-color: var(--pst-color-text-base);
 }
 
 

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/js/table.js

@@ -0,0 +1,11 @@
+$(document).ready( function () {
+    $('table.datatable').DataTable();
+} );
+
+$(document).ready( function () {
+    $('table.gridtable').GridTable();
+} );
+
+$(document).ready( function () {
+    $('table.gianttables').GiantTable();
+} );