docs: reformat the documentation (#396)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martinez <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>
Co-authored-by: Sébastien Morais <[email protected]>

Author: 5 people

.github/workflows/ci_cd.yml

@@ -60,6 +60,9 @@ jobs:
         uses: ansys/actions/doc-build@v6
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
+          add-pdf-html-docs-as-assets: true
+          requires-xvfb: true
+          dependencies: 'pandoc'
 
   doc-deploy-development:
     name: Doc dev version deploy

.gitignore

@@ -157,3 +157,8 @@ cython_debug/
 
 # Sphinx auto-generated
 doc/source/_autosummary/
+# rendering of sphinx gallery examples
+doc/source/examples/gallery-examples/
+doc/source/sg_execution_times.rst
+# rendering of sphinx autoapi examples
+doc/source/examples/examples/

.pre-commit-config.yaml

@@ -10,12 +10,12 @@ repos:
   - id: isort
 
 - repo: https://github.com/PyCQA/flake8
-  rev: 7.0.0
+  rev: 7.1.0
   hooks:
   - id: flake8
 
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.2.6
+  rev: v2.3.0
   hooks:
   - id: codespell
 
@@ -41,7 +41,7 @@ repos:
 
 # this validates our github workflow files
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.28.4
+  rev: 0.28.5
   hooks:
     - id: check-github-workflows
 
@@ -54,7 +54,7 @@ repos:
     exclude: 'src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/'
 
 - repo: https://github.com/ansys/pre-commit-hooks
-  rev: v0.3.1
+  rev: v0.3.2
   hooks:
   - id: add-license-headers
     args:

doc/Makefile

@@ -6,22 +6,26 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
+AUTOAPI_OUTDIR = source/examples/examples
+GALLERY_EXAMPLES = gallery-examples
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile clean pdf
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# customized clean due to api examples
+# customized clean due to api examples and sphinx-gallery
 clean:
 	rm -rf $(BUILDDIR)
-	find . -type d -name "_autosummary" -exec rm -rf {} +
+	find . -type d -name "$(GALLERY_EXAMPLES)" -exec rm -rf {} +
+	find . -type d -path "./$(AUTOAPI_OUTDIR)" -exec rm -rf {} +
+	echo Cleanup complete.
 
 # customized pdf due to svg issue
 pdf:

doc/changelog.d/396.dependencies.md

@@ -0,0 +1 @@
+docs: reformat the documentation

doc/make.bat

@@ -9,9 +9,12 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=source
 set BUILDDIR=_build
+set GALLERY_EXAMPLES=%SOURCEDIR%\examples\gallery-examples
+set AUTOAPI_OUTDIR=%SOURCEDIR%\examples\examples\
 
 if "%1" == "" goto help
 if "%1" == "pdf" goto pdf
+if "%1" == "clean" goto clean
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -33,10 +36,15 @@ goto end
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :pdf
-	%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-	cd "%BUILDDIR%\latex"
-	for %%f in (*.tex) do (
-	pdflatex "%%f" --interaction=nonstopmode)
+%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+cd "%BUILDDIR%\latex"
+for %%f in (*.tex) do (
+pdflatex "%%f" --interaction=nonstopmode)
+
+:clean
+if exist %BUILDDIR% rmdir /S /Q %BUILDDIR%
+if exist %GALLERY_EXAMPLES% rmdir /S /Q %GALLERY_EXAMPLES%
+if exist %AUTOAPI_OUTDIR% rmdir /S /Q %AUTOAPI_OUTDIR%
 
 :end
 popd

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/pyansys_light_square.png doc/source/_static/pyansys_light_square.png

@@ -2,12 +2,14 @@
 
 from datetime import datetime
 import os
+from pathlib import Path
+from typing import List
 
 from github import Github
+import pyvista
+import requests
 from sphinx.builders.latex import LaTeXBuilder
 
-LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
-
 from ansys_sphinx_theme import (
     __version__,
     ansys_favicon,
@@ -21,6 +23,10 @@
     watermark,
 )
 
+THIS_PATH = Path(__file__).parent.resolve()
+EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
+API_TEMPLATES = (THIS_PATH / "examples" / "autoapi").resolve()
+
 # Project information
 project = "ansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -29,21 +35,23 @@
 cname = os.getenv("DOCUMENTATION_CNAME", "sphinxdocs.ansys.com")
 switcher_version = get_version_match(__version__)
 
-# use the default ansys logo
+# HTML configuration
 html_logo = ansys_logo_black
+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"]
 
-
-# In the html_context dictionary in conf.py
 html_context = {
     "github_user": "ansys",
     "github_repo": "ansys-sphinx-theme",
     "github_version": "main",
     "doc_path": "doc/source",
 }
 
-
-# specify the location of your github repo
 html_theme_options = {
     "github_url": "https://github.com/ansys/ansys-sphinx-theme",
     "contact_mail": "[email protected]",
@@ -61,20 +69,30 @@
             f"ansys-sphinx-theme-v{convert_version_to_pymeilisearch(__version__)}": "ansys-sphinx-theme",  # noqa: E501
         },
     },
+    "ansys_sphinx_theme_autoapi": {
+        "project": project,
+        "directory": "src/ansys_sphinx_theme/examples",
+        "output": "examples/",
+        "own_page_level": "function",
+    },
 }
 
-html_short_title = html_title = "Ansys Sphinx Theme"
-
 # Sphinx extensions
 extensions = [
+    "ansys_sphinx_theme.extension.autoapi",
+    "nbsphinx",
+    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "numpydoc",
     "sphinx.ext.intersphinx",
-    "notfound.extension",
+    "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx_gallery.gen_gallery",
     "sphinx_jinja",
+    "notfound.extension",
 ]
 
 # Intersphinx mapping
@@ -86,33 +104,19 @@
 # numpydoc configuration
 numpydoc_show_class_members = False
 numpydoc_xref_param_type = True
-
-# Consider enabling numpydoc validation. See:
-# https://numpydoc.readthedocs.io/en/latest/validation.html#
 numpydoc_validate = True
 numpydoc_validation_checks = {
     "GL06",  # Found unknown section
     "GL07",  # Sections are in the wrong order.
-    "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
-    # "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"
+    "RT02",  # The first line of the Returns section should contain only the type
 }
 
-# Favicon
-html_favicon = ansys_favicon
-
-# static path
-html_static_path = ["_static"]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+suppress_warnings = ["config.cache"]
 
 # The suffix(es) of source filenames.
 source_suffix = ".rst"
@@ -121,39 +125,57 @@
 master_doc = "index"
 
 # additional logos for the latex coverpage
+LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
 latex_additional_files = [watermark, ansys_logo_white, ansys_logo_white_cropped]
-
-# change the preamble of latex with customized title page
-# variables are the title of pdf, watermark
 latex_elements = {"preamble": latex.generate_preamble(html_title)}
 
 # Not found page
 notfound_context = {
     "body": generate_404(),
 }
-
 notfound_no_urls_prefix = True
 
 # ONLY FOR ANSYS-SPHINX-THEME
+exclude_patterns = [
+    "links.rst",
+    "examples/sphinx-gallery/README.rst",
+    "examples/gallery-examples/*.ipynb",
+]
+rst_epilog = ""
+with open("links.rst") 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",
+}
 
-from pathlib import Path
-from typing import List
-
-import requests
-
-THIS_PATH = Path(__file__).parent.resolve()
-
-EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve()
+# Ensure that offscreen rendering is used for docs generation
+# Preferred plotting style for documentation
+pyvista.BUILDING_GALLERY = True
 
-linkcheck_ignore = []
+linkcheck_ignore = ["https://sphinxdocs.ansys.com/version/dev/*"]
 if switcher_version != "dev":
     linkcheck_ignore.append(
         f"https://github.com/ansys/ansys-sphinx-theme/releases/tag/v{__version__}"
     )
 
 
 def extract_example_links(
-    repo_fullname: str, path_relative_to_root: str, exclude_files: List[str]
+    repo_fullname: str, path_relative_to_root: str, exclude_files: List[str] = []
 ) -> List[str]:
     """
     Extract example links from a specific GitHub repository.
@@ -175,7 +197,8 @@ def extract_example_links(
     g = Github()
     repo = g.get_repo(repo_fullname)
     contents = repo.get_contents(path_relative_to_root)
-
+    if not isinstance(contents, list):
+        contents = [contents]
     example_links = []
     for content in contents:
         if content.type == "dir":
@@ -225,4 +248,19 @@ def download_and_process_files(example_links: List[str]) -> List[str]:
 )
 file_names = download_and_process_files(example_links)
 
-jinja_contexts = {"examples": {"inputs_examples": file_names}}
+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},
+    "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
+}