From ba6fe6a72a217126efc92c3fcd603e660ef8722b Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 17 Oct 2024 12:22:35 +0200 Subject: [PATCH 1/8] doc: enable BUILD_EXAMPLES envar --- doc/source/conf.py | 57 ++++++++++++++++++++++++++++---------------- doc/source/index.rst | 52 ++++++++++++++++++++++++---------------- 2 files changed, 68 insertions(+), 41 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 7a90ae23..5dae6218 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -176,6 +176,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 +253,33 @@ 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: + # 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} + + +print(f"JINJA CONTEXTS: {jinja_contexts}") diff --git a/doc/source/index.rst b/doc/source/index.rst index 55954264..5c81a19b 100644 --- a/doc/source/index.rst +++ b/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 From 8334ce2fcab203e1cc95f120256750f950c08ad8 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 17 Oct 2024 10:24:50 +0000 Subject: [PATCH 2/8] chore: adding changelog file 553.documentation.md [dependabot-skip] --- doc/changelog.d/553.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/553.documentation.md diff --git a/doc/changelog.d/553.documentation.md b/doc/changelog.d/553.documentation.md new file mode 100644 index 00000000..a8192fee --- /dev/null +++ b/doc/changelog.d/553.documentation.md @@ -0,0 +1 @@ +doc: allow developer to skip examples build \ No newline at end of file From 272656f80e43e038c122e33c39cf203254992601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Mart=C3=ADnez?= <28702884+jorgepiloto@users.noreply.github.com> Date: Thu, 17 Oct 2024 14:01:56 +0200 Subject: [PATCH 3/8] fix: remove unnecessary print Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> --- doc/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 5dae6218..d1b47029 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -282,4 +282,3 @@ def download_and_process_files(example_links: List[str]) -> List[str]: jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links} -print(f"JINJA CONTEXTS: {jinja_contexts}") From 171b4591709c9d0bc076c20d9773afadd4352081 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 17 Oct 2024 12:44:38 +0200 Subject: [PATCH 4/8] fix: extensions loading --- doc/source/conf.py | 80 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index d1b47029..d710ab51 100644 --- a/doc/source/conf.py +++ b/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,17 +66,10 @@ } -nbsphinx_prolog = """ -Download this example as a :download:`Jupyter notebook `. - ----- -""" - # Sphinx extensions extensions = [ - "ansys_sphinx_theme.extension.autoapi", - "nbsphinx", "numpydoc", + "sphinx_design", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.intersphinx", @@ -93,8 +77,8 @@ "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": @@ -262,6 +226,44 @@ def download_and_process_files(example_links: List[str]) -> List[str]: 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 `. + + ---- + """ + 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", From 52fc5c1c9bdb077d982f52b9ccaccf55259c5f72 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 17 Oct 2024 14:15:18 +0200 Subject: [PATCH 5/8] fix: code style --- doc/source/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index d710ab51..639343ef 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -282,5 +282,3 @@ def download_and_process_files(example_links: List[str]) -> List[str]: jinja_contexts["examples"] = {"inputs_examples": file_names} jinja_contexts["admonitions"] = {"inputs_admonitions": admonitions_links} - - From 8d5fca0f683ef9736dfcaedfa1ae0dae19797c55 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 18 Oct 2024 11:20:49 +0200 Subject: [PATCH 6/8] dbg: title for notebook cell --- doc/source/examples/nbsphinx/jupyter-notebook.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/examples/nbsphinx/jupyter-notebook.ipynb b/doc/source/examples/nbsphinx/jupyter-notebook.ipynb index 2a54e5c7..4e1c083d 100644 --- a/doc/source/examples/nbsphinx/jupyter-notebook.ipynb +++ b/doc/source/examples/nbsphinx/jupyter-notebook.ipynb @@ -96,7 +96,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Render a data frame" + "## Render a data frame" ] }, { From 1fc76c9ee59f93e6d213138d4b6d71d9e118b347 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 18 Oct 2024 11:30:32 +0200 Subject: [PATCH 7/8] dbg: title for notebook cell --- doc/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 639343ef..45533b01 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -253,10 +253,10 @@ def download_and_process_files(example_links: List[str]) -> List[str]: } nbsphinx_prolog = """ - Download this example as a :download:`Jupyter notebook `. +Download this example as a :download:`Jupyter notebook `. - ---- - """ +---- +""" nbsphinx_execute = "always" nbsphinx_thumbnails = { "examples/nbsphinx/jupyter-notebook": "_static/pyansys_light_square.png", From 9dd4c7a211b39b1db484549a67d0348fc43b1d77 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 18 Oct 2024 11:40:30 +0200 Subject: [PATCH 8/8] fix: restore file --- doc/source/examples/nbsphinx/jupyter-notebook.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/examples/nbsphinx/jupyter-notebook.ipynb b/doc/source/examples/nbsphinx/jupyter-notebook.ipynb index 4e1c083d..2a54e5c7 100644 --- a/doc/source/examples/nbsphinx/jupyter-notebook.ipynb +++ b/doc/source/examples/nbsphinx/jupyter-notebook.ipynb @@ -96,7 +96,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Render a data frame" + "# Render a data frame" ] }, {