Add examples of extension libraries.

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,74 @@
     "body": generate_404(),
 }
 notfound_no_urls_prefix = True
+
+
+def extract_example_links(archive_url: str, exclude_files: List[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.
+    exclude_files : list of str
+        A list of files to exclude from the returned example links.
+
+    Returns
+    -------
+    list
+        List of example links.
+    """
+    response = requests.get(archive_url)
+    soup = BeautifulSoup(response.content, "html5lib")
+    links = soup.find_all("a")
+    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, exclude_files=["article-info.txt"])
+file_names = download_and_process_files(example_links)
+
+jinja_contexts = {"examples": {"inputs_examples": file_names}}

doc/source/examples/index.rst

@@ -0,0 +1,29 @@
+========
+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 of the sphinx design rendered using the `ansys-sphinx-theme`.
+
+   .. grid-item::
+      .. card:: Table
+         :link: table
+         :link-type: ref
+
+            Examples of tables with JavaScript and RST rendered using the `ansys-sphinx-theme`.
+            It also recommends improving documentation with 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,24 @@
+.. _sphinx-design:
+
+Sphinx design
+=============
+The rendering of sphinx design with ansys sphinx theme.
+To access the full documentation for the sphinx design package,
+please refer `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,109 @@
+.. _table:
+
+Table
+=====
+The table directive with ansys sphinx theme allows for rendering of tables.
+There are different types of tables, such as the data table, longtable-centered, 
+and table-centered, each serving different purposes.
+
+Data table
+----------
+This is an example of a data table that can be rendered using the table directive.
+It consists of three columns representing the variables A, B, and A and B respectively.
+Each row represents a different combination of True and False for variables A and B.
+The `datatable` class can be used to style 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
+------------------
+The longtable-centered class can be used to create a table that
+spans multiple pages and is centered horizontally.
+This is useful for tables that have a large number of rows or columns.
+Here is an example of a longtable-centered:
+
+.. 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
+--------------
+The table-centered class can be used to create a table that is horizontally centered.
+This is useful for tables that have only a few columns.
+Here is an example of a 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

doc/styles/Vocab/ANSYS/accept.txt

@@ -2,4 +2,5 @@ ANSYS
 Ansys
 ansys
 Ansys Sphinx Theme
-boolean
+boolean
+datatable

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==1.1",
+    "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,7 +110,9 @@ 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)))
+    app.add_js_file("https://cdn.datatables.net/1.10.23/js/jquery.dataTables.min.js")
+    app.add_css_file("https://cdn.datatables.net/1.10.23/css/jquery.dataTables.min.css")
     # Add templates for autosummary
     app.config.templates_path.append(str(TEMPLATES_PATH))