diff --git a/doc/changelog.d/736.added.md b/doc/changelog.d/736.added.md new file mode 100644 index 000000000..985425766 --- /dev/null +++ b/doc/changelog.d/736.added.md @@ -0,0 +1 @@ +Test mini gallery with `autoapi` and `autosummary` \ No newline at end of file diff --git a/doc/source/_templates/autosummary/base.rst b/doc/source/_templates/autosummary/base.rst new file mode 100644 index 000000000..fce87dbd0 --- /dev/null +++ b/doc/source/_templates/autosummary/base.rst @@ -0,0 +1,11 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} + + +.. minigallery:: + :add-heading: Examples using {{ objname }} + + {{ fullname }} \ No newline at end of file diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..dda05994f --- /dev/null +++ b/doc/source/_templates/autosummary/class.rst @@ -0,0 +1,38 @@ +{{ objname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :toctree: + {% for item in methods %} + {% if item != "__init__" %} + {{ name }}.{{ item }} + {% endif %} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + +.. minigallery:: + :add-heading: Examples using {{ objname }} + + {{ fullname }} \ No newline at end of file diff --git a/doc/source/_templates/autosummary/module.rst b/doc/source/_templates/autosummary/module.rst new file mode 100644 index 000000000..5592b0454 --- /dev/null +++ b/doc/source/_templates/autosummary/module.rst @@ -0,0 +1,72 @@ +.. vale off + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ fullname }} + +{% block attributes %} +{% if attributes %} +.. autosummary:: + :toctree: + :caption: Attributes + +{% for item in attributes %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block functions %} +{% if functions %} +.. autosummary:: + :toctree: + :caption: Functions + +{% for item in functions %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block classes %} +{% if classes %} +.. autosummary:: + :toctree: + :caption: Classes + +{% for item in classes %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block exceptions %} +{% if exceptions %} +.. autosummary:: + :toctree: + :caption: Classes + +{% for item in exceptions %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block modules %} +{% if modules %} +.. autosummary:: + :toctree: + :recursive: + :caption: Modules +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +.. minigallery:: + :add-heading: Examples using {{ objname }} + + {{ module }}.{{ objname }} + +.. vale on \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 6f2949fa4..16aed5343 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -198,7 +198,8 @@ def extract_example_links( list List of example links. """ - g = Github() + token = os.getenv("GITHUB_TOKEN") + g = Github(token) if token else Github() repo = g.get_repo(repo_fullname) contents = repo.get_contents(path_relative_to_root) if not isinstance(contents, list): @@ -275,6 +276,8 @@ def download_and_process_files(example_links: List[str]) -> List[str]: "download_all_examples": False, # Modules for which function level galleries are created. In "image_scrapers": ("pyvista", "matplotlib", "plotly.io._sg_scraper.plotly_sg_scraper"), + "doc_module": ("ansys_sphinx_theme",), + "backreferences_dir": "api/_gallery_backreferences", "default_thumb_file": str(PYANSYS_LIGHT_SQUARE), } pyvista.BUILDING_GALLERY = True diff --git a/doc/source/examples/sphinx-gallery/theme-example.py b/doc/source/examples/sphinx-gallery/theme-example.py new file mode 100644 index 000000000..952d69f6c --- /dev/null +++ b/doc/source/examples/sphinx-gallery/theme-example.py @@ -0,0 +1,59 @@ +# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + +# noqa: D205, D400 +"""Test mini gallery with the ansys-sphinx-theme.""" + +############################################################################### +# print a message to the console +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# This code plots a simple sphere using PyVista. +from ansys_sphinx_theme.examples.sample_func import func # noqa: E402 + +print("This is an example of a Sphinx Gallery theme example.") + +print(func) + +############################################################################### +# print a message to the console +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# This is to print the console + + +from ansys_sphinx_theme.examples import samples # noqa: E402 + +examples = samples.ExampleClass("mystr", ["apple", "orange"], 3) +print(examples) + +################################################################################# +# plot a simple sphere +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# This code plots a simple sphere using PyVista. + +import pyvista as pv # noqa: E402 + +pv.set_jupyter_backend("html") + +sphere = pv.Sphere() +sphere.plot() + +############################################################################### diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst index 8353ea1b1..d0c2fa254 100644 --- a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/class.rst @@ -208,5 +208,11 @@ Import detail {% endif %} {% endif %} + + +.. minigallery:: + :add-heading: Examples using {{ obj.obj["full_name"] }} + + {{ obj.obj["full_name"] }} {# ---------------------- End class details -------------------- #} {% endif %} diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst index 2cc1f662c..521a2c42b 100644 --- a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/python/module.rst @@ -249,4 +249,9 @@ Module detail {% endif %} {% endif %} +.. minigallery:: + :add-heading: Examples using {{ obj.obj["full_name"] }} + + {{ obj.obj["full_name"] }} + {# ---------------------- End module detail description -------------------- #} diff --git a/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/module.rst b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/module.rst new file mode 100644 index 000000000..5592b0454 --- /dev/null +++ b/src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autosummary/module.rst @@ -0,0 +1,72 @@ +.. vale off + +{{ fullname | escape | underline}} + +.. currentmodule:: {{ fullname }} + +{% block attributes %} +{% if attributes %} +.. autosummary:: + :toctree: + :caption: Attributes + +{% for item in attributes %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block functions %} +{% if functions %} +.. autosummary:: + :toctree: + :caption: Functions + +{% for item in functions %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block classes %} +{% if classes %} +.. autosummary:: + :toctree: + :caption: Classes + +{% for item in classes %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block exceptions %} +{% if exceptions %} +.. autosummary:: + :toctree: + :caption: Classes + +{% for item in exceptions %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +{% block modules %} +{% if modules %} +.. autosummary:: + :toctree: + :recursive: + :caption: Modules +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} + +.. minigallery:: + :add-heading: Examples using {{ objname }} + + {{ module }}.{{ objname }} + +.. vale on \ No newline at end of file