Build Examples in documentation automatically (#173)

Author: saimanikant

.github/workflows/ci_cd.yml

@@ -96,15 +96,12 @@ jobs:
           sudo apt update
           sudo apt install latexmk texlive-latex-extra
 
-      - name: Generate the documentation with tox
-        run: tox -e doc
-
-      - name: Upload HTML Documentation
-        uses: actions/upload-artifact@v4
+      - name: "Run Ansys documentation building action"
+        uses: ansys/actions/doc-build@v8
         with:
-          name: documentation-html
-          path: doc/_build/html
-          retention-days: 7
+          python-version: ${{ env.MAIN_PYTHON_VERSION }}
+          check-links: false
+          sphinxopts: "-j auto -W --color --keep-going"
 
   smoke-tests:
     name: Build and Smoke tests

.gitignore

@@ -75,6 +75,8 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+doc/source/examples/*
+doc/**/sg_execution_times.rst
 
 # PyBuilder
 .pybuilder/

CONTRIBUTORS.md

@@ -3,7 +3,6 @@
 ## Project Lead or Owner
 
 * [Michal Pawlik](https://github.com/nezgrath)
-* [Oliver Koenig](https://github.com/ojkoenig)
 
 ## Individual Contributors
 

doc/source/api/client.rst

@@ -40,28 +40,50 @@
 
 # Sphinx extensions
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx_design",
-    "sphinx_tabs.tabs",
-    "sphinxcontrib.autodoc_pydantic",
     "sphinx_jinja",
+    "numpydoc",
+    "ansys_sphinx_theme.extension.autoapi",
+    "sphinx_gallery.gen_gallery",
 ]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+nbsphinx_execute = "always"
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    "examples_dirs": ["../../examples"],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["examples"],
+    # Pattern to search for example files
+    "filename_pattern": r".*\.py",
+    "run_stale_examples": False,         # Do not re-run examples
+    "plot_gallery": False,
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    # directory where function granular galleries are stored
+    "backreferences_dir": None,
+    # Modules for which function level galleries are created in
+    "doc_module": "ansys-hps-data-transfer-client",
+    "ignore_pattern": "flycheck*",
+    "thumbnail_size": (350, 350),
+    "remove_config_comments": True,
+    "show_signature": False,
+}
+
+
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    # kept here as an example
-    # "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
-    # "numpy": ("https://numpy.org/devdocs", None),
-    # "matplotlib": ("https://matplotlib.org/stable", None),
-    # "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
-    # "pyvista": ("https://docs.pyvista.org/", None),
-    # "grpc": ("https://grpc.github.io/grpc/python/", None),
+    #"scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "numpy": ("https://numpy.org/devdocs", None),
+    #"matplotlib": ("https://matplotlib.org/stable", None),
+    #"pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    #"pyvista": ("https://docs.pyvista.org/", None),
+    #"grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
 # numpydoc configuration
@@ -74,22 +96,35 @@
 numpydoc_validation_checks = {
     "GL06",  # Found unknown section
     "GL07",  # Sections are in the wrong order.
-    "GL08",  # The object does not have a docstring
+    #"GL08",  # The object does not have a docstring
     "GL09",  # Deprecation warning should precede extended summary
     "GL10",  # reST directives {directives} must be followed by two colons
     "SS01",  # No summary found
-    "SS02",  # Summary does not start with a capital letter
+    # "SS02",  # Summary does not start with a capital letter
     # "SS03", # Summary does not end with a period
     "SS04",  # Summary contains heading whitespaces
     # "SS05", # Summary must start with infinitive verb, not third person
     "RT02",  # The first line of the Returns section should contain only the
     # type, unless multiple values are being returned"
 }
 
-# autodoc/autosummary flags
-autoclass_content = "both"
-# autodoc_default_flags = ["members"]
-autosummary_generate = True
+
+autoapi_type = "python"
+autoapi_dirs = ["../../src"]
+autoapi_generate_api_docs = True
+autoapi_root = "api"
+
+# Configuration for Sphinx autoapi
+suppress_warnings = [
+    "autoapi.duplicate_object",
+    "design.grid",
+    "docutils",
+    "toc.not_readable",
+    "toc.not_included",
+    "toc.excluded",
+    "ref.python",
+    "design.fa-build",
+]
 
 
 # static path
@@ -104,6 +139,7 @@
 # The master toctree document.
 master_doc = "index"
 
+
 # Keep these while the repository is private
 linkcheck_ignore = [
     "https://github.com/ansys-internal/hps-data-transfer-client//*",
@@ -115,3 +151,43 @@
 # available until the release is published.
 if switcher_version != "dev":
     linkcheck_ignore.append(f"https://github.com/ansys/ansys.hps.data_transfer_client/releases/tag/v{__version__}")
+
+# Examples gallery customization
+nbsphinx_execute = "always"
+
+# -- Declare the Jinja context -----------------------------------------------
+exclude_patterns = [
+    "examples/**/*.txt",
+    "api/client/client/index.rst",
+    "api/client/index.rst",
+]
+
+BUILD_API = True
+if not BUILD_API:
+    exclude_patterns.append("autoapi")
+
+BUILD_EXAMPLES = True
+if not BUILD_EXAMPLES:
+    exclude_patterns.append("examples/**")
+    exclude_patterns.append("examples.rst")
+
+jinja_contexts = {
+    "main_toctree": {
+        "build_api": BUILD_API,
+        "build_examples": BUILD_EXAMPLES,
+    }
+}
+
+
+def prepare_jinja_env(jinja_env) -> None:
+    """Customize the jinja env.
+
+    Notes
+    -----
+    See https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.Environment
+
+    """
+    jinja_env.globals["project_name"] = project
+
+
+autoapi_prepare_jinja_env = prepare_jinja_env