doc: allow developer to skip examples build

doc/changelog.d/553.documentation.md

@@ -0,0 +1 @@
+doc: allow developer to skip examples build

doc/source/conf.py

@@ -36,9 +36,7 @@
 html_favicon = ansys_favicon
 html_theme = "ansys_sphinx_theme"
 html_short_title = html_title = "Ansys Sphinx Theme"
-# static path
 html_static_path = ["_static"]
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 html_context = {
@@ -59,13 +57,6 @@
         "json_url": f"https://{cname}/versions.json",
         "version_match": get_version_match(__version__),
     },
-    "ansys_sphinx_theme_autoapi": {
-        "project": project,
-        "directory": "src/ansys_sphinx_theme/examples",
-        "output": "examples/api",
-        "own_page_level": "function",
-        "package_depth": 1,
-    },
     "logo": "ansys",
     "static_search": {
         "threshold": 0.2,
@@ -75,26 +66,19 @@
 }
 
 
-nbsphinx_prolog = """
-Download this example as a :download:`Jupyter notebook </{{ env.docname }}.ipynb>`.
-
-----
-"""
-
 # Sphinx extensions
 extensions = [
-    "ansys_sphinx_theme.extension.autoapi",
-    "nbsphinx",
     "numpydoc",
+    "sphinx_design",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
-    "sphinx_gallery.gen_gallery",
     "notfound.extension",
+    "sphinx_jinja",
 ]
 
 # Intersphinx mapping
@@ -142,32 +126,12 @@
     "links.rst",
     "examples/sphinx-gallery/README.rst",
     "examples/gallery-examples/*.ipynb",
+    "sg_execution_times.rst",
 ]
 rst_epilog = ""
 with Path.open(THIS_PATH / "links.rst", "r") as f:
     rst_epilog += f.read()
 
-sphinx_gallery_conf = {
-    # path to your examples scripts
-    "examples_dirs": ["examples/sphinx-gallery"],
-    # path where to save gallery generated examples
-    "gallery_dirs": ["examples/gallery-examples"],
-    # Pattern to search for example files
-    "filename_pattern": r"sphinx_gallery\.py",
-    # Remove the "Download all examples" button from the top level gallery
-    "download_all_examples": False,
-    # Modules for which function level galleries are created.  In
-    "image_scrapers": ("pyvista", "matplotlib"),
-    "default_thumb_file": "source/_static/pyansys_light_square.png",
-}
-nbsphinx_execute = "always"
-nbsphinx_thumbnails = {
-    "examples/nbsphinx/jupyter-notebook": "_static/pyansys_light_square.png",
-}
-
-# Ensure that offscreen rendering is used for docs generation
-# Preferred plotting style for documentation
-pyvista.BUILDING_GALLERY = True
 
 linkcheck_ignore = ["https://sphinxdocs.ansys.com/version/*"]
 if switcher_version != "dev":
@@ -176,6 +140,16 @@
     )
 
 
+# Configure the Jinja contexts
+
+jinja_contexts = {
+    "install_guide": {
+        "version": f"v{version}" if not version.endswith("dev0") else "main",
+    },
+    "pdf_guide": {"version": get_version_match(__version__)},  # noqa: E501
+}
+
+
 def extract_example_links(
     repo_fullname: str, path_relative_to_root: str, exclude_files: List[str] = []
 ) -> List[str]:
@@ -243,26 +217,68 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
     return file_names
 
 
-example_links = extract_example_links(
-    "executablebooks/sphinx-design",
-    "docs/snippets/rst",
-    exclude_files=["article-info.txt"],
-)
-file_names = download_and_process_files(example_links)
+# Skip building examples if desired
+BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
+jinja_contexts["main_toctree"] = {"build_examples": BUILD_EXAMPLES}
 
-admonitions_links = extract_example_links(
-    "pydata/pydata-sphinx-theme",
-    "docs/examples/kitchen-sink/admonitions.rst",
-)
+if not BUILD_EXAMPLES:
+    exclude_patterns.extend(["examples.rst", "examples/**", "examples/api/**"])
 
-admonitions_links = download_and_process_files(admonitions_links)
-todo_include_todos = True  # admonition todo needs this to be True
 
-jinja_contexts = {
-    "examples": {"inputs_examples": file_names},
-    "admonitions": {"inputs_admonitions": admonitions_links},
-    "install_guide": {
-        "version": f"v{version}" if not version.endswith("dev0") else "main",
-    },
-    "pdf_guide": {"version": get_version_match(__version__)},  # noqa: E501
-}
+else:
+    # Autoapi examples
+    extensions.append("ansys_sphinx_theme.extension.autoapi")
+    html_theme_options["ansys_sphinx_theme_autoapi"] = {
+        "project": project,
+        "directory": "src/ansys_sphinx_theme/examples",
+        "output": "examples/api",
+        "own_page_level": "function",
+        "package_depth": 1,
+    }
+
+    # Gallery of examples
+    extensions.extend(["nbsphinx", "sphinx_gallery.gen_gallery"])
+    sphinx_gallery_conf = {
+        # path to your examples scripts
+        "examples_dirs": ["examples/sphinx-gallery"],
+        # path where to save gallery generated examples
+        "gallery_dirs": ["examples/gallery-examples"],
+        # Pattern to search for example files
+        "filename_pattern": r"sphinx_gallery\.py",
+        # Remove the "Download all examples" button from the top level gallery
+        "download_all_examples": False,
+        # Modules for which function level galleries are created.  In
+        "image_scrapers": ("pyvista", "matplotlib"),
+        "default_thumb_file": "source/_static/pyansys_light_square.png",
+    }
+
+    nbsphinx_prolog = """
+Download this example as a :download:`Jupyter notebook </{{ env.docname }}.ipynb>`.
+
+----
+"""
+    nbsphinx_execute = "always"
+    nbsphinx_thumbnails = {
+        "examples/nbsphinx/jupyter-notebook": "_static/pyansys_light_square.png",
+    }
+
+    pyvista.BUILDING_GALLERY = True
+
+    # Third party examples
+    example_links = extract_example_links(
+        "executablebooks/sphinx-design",
+        "docs/snippets/rst",
+        exclude_files=["article-info.txt"],
+    )
+    file_names = download_and_process_files(example_links)
+
+    admonitions_links = extract_example_links(
+        "pydata/pydata-sphinx-theme",
+        "docs/examples/kitchen-sink/admonitions.rst",
+    )
+
+    admonitions_links = download_and_process_files(admonitions_links)
+    todo_include_todos = True  # admonition todo needs this to be True
+
+    jinja_contexts["examples"] = {"inputs_examples": file_names}
+    jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links}

doc/source/index.rst

@@ -8,32 +8,42 @@ This theme is specifically tailored for documentation related to Ansys projects
 helping to ensure consistency in its look and feel. Various useful extensions
 are included in the theme to make documentation more appealing and user-friendly.
 
-.. grid:: 2
-    :gutter: 2 2 3 4
+.. jinja:: main_toctree
 
-    .. grid-item-card:: Getting started :fa:`person-running`
-        :link: getting-started
-        :link-type: doc
+    .. grid:: 2
+        :gutter: 2 2 3 4
 
-        Learn how to install the Ansys Sphinx Theme.
+        .. grid-item-card:: Getting started :fa:`person-running`
+            :link: getting-started
+            :link-type: doc
 
-    .. grid-item-card:: User guide :fa:`book-open-reader`
-        :link: user-guide
-        :link-type: doc
+            Learn how to install the Ansys Sphinx Theme.
 
-        Learn how to use the capabilities and features of this theme.
+        .. grid-item-card:: User guide :fa:`book-open-reader`
+            :link: user-guide
+            :link-type: doc
 
-    .. grid-item-card:: Examples :fa:`laptop-code`
-        :link: examples
-        :link-type: doc
+            Learn how to use the capabilities and features of this theme.
 
-        Explore examples that show how to integrate third-party extensions with this theme.
+        {% if build_examples %}
 
-.. toctree::
-   :hidden:
-   :maxdepth: 3
+        .. grid-item-card:: Examples :fa:`laptop-code`
+            :link: examples
+            :link-type: doc
 
-   getting-started.rst
-   user-guide.rst
-   examples.rst
-   changelog
+            Explore examples that show how to integrate third-party extensions with this theme.
+
+        {% endif %}
+
+.. jinja:: main_toctree
+
+    .. toctree::
+       :hidden:
+       :maxdepth: 3
+
+       getting-started.rst
+       user-guide.rst
+       {% if build_examples %}
+       examples.rst
+       {% endif %}
+       changelog