feat: Finished documentation

.gitignore

@@ -70,7 +70,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
+doc/source/api
+doc/source/examples/*
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
   hooks:
   - id: pydocstyle
     additional_dependencies: [tomli]
-    exclude: "tests/"
+    exclude: "tests/|examples/"
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.5.0

doc/source/conf.py

@@ -1,7 +1,6 @@
 """Sphinx documentation configuration file."""
 
 from datetime import datetime
-import json
 import os
 from pathlib import Path
 
@@ -15,46 +14,18 @@
     pyansys_logo_black,
     watermark,
 )
-import requests
+import pyvista
 from sphinx.builders.latex import LaTeXBuilder
 
-from ansys.visualizer.core import __version__
+from ansys.visualizer import __version__
 
 os.environ["PYANSYS_VISUALIZER_DOC_BUILD"] = "true"
 
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
 
 
-def get_wheelhouse_assets_dictionary():
-    """Auxiliary method to build the wheelhouse assets dictionary."""
-    assets_context_os = ["Linux", "Windows", "MacOS"]
-    assets_context_runners = ["ubuntu-latest", "windows-latest", "macos-latest"]
-    assets_context_python_versions = ["3.9", "3.10", "3.11", "3.12"]
-    if get_version_match(__version__) == "dev":
-        # Just point to the latest version
-        assets_context_version = json.loads(
-            requests.get(
-                "https://api.github.com/repos/ansys/pyansys-visualizer/releases/latest"
-            ).content
-        )["name"]
-    else:
-        assets_context_version = f"v{__version__}"
-
-    assets = {}
-    for assets_os, assets_runner in zip(assets_context_os, assets_context_runners):
-        download_links = []
-        for assets_py_ver in assets_context_python_versions:
-            temp_dict = {
-                "os": assets_os,
-                "runner": assets_runner,
-                "python_versions": assets_py_ver,
-                "latest_released_version": assets_context_version,
-                "prefix_url": f"https://github.com/ansys/pyansys-visualizer/releases/download/{assets_context_version}",  # noqa: E501
-            }
-            download_links.append(temp_dict)
-
-        assets[assets_os] = download_links
-    return assets
+pyvista.BUILDING_GALLERY = True
+pyvista.OFF_SCREEN = True
 
 
 # Project information
@@ -117,14 +88,37 @@ def get_wheelhouse_assets_dictionary():
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "nbsphinx",
-    "myst_parser",
     "jupyter_sphinx",
     "sphinx_design",
     "sphinx_jinja",
     "autoapi.extension",
     "numpydoc",
+    "sphinx_gallery.gen_gallery",
 ]
 
+
+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",
+    # 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-visualizer",
+    "image_scrapers": ("pyvista"),
+    "ignore_pattern": "flycheck*",
+    "thumbnail_size": (350, 350),
+    "remove_config_comments": True,
+    "show_signature": False,
+}
+
+
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.11", None),
@@ -136,10 +130,6 @@ def get_wheelhouse_assets_dictionary():
     "beartype": ("https://beartype.readthedocs.io/en/stable/", None),
     "docker": ("https://docker-py.readthedocs.io/en/stable/", None),
     "pypim": ("https://pypim.docs.pyansys.com/version/stable", None),
-    "ansys.visualizer.core": (
-        f"https://visualizer.docs.pyansys.com/version/{switcher_version}",
-        None,
-    ),
 }
 
 # numpydoc configuration
@@ -164,13 +154,6 @@ def get_wheelhouse_assets_dictionary():
     # type, unless multiple values are being returned"
 }
 
-# static path
-html_static_path = ["_static"]
-
-html_css_files = [
-    "custom.css",
-]
-
 html_favicon = ansys_favicon
 
 # Add any paths that contain templates here, relative to this directory.
@@ -202,12 +185,9 @@ def get_wheelhouse_assets_dictionary():
 autoapi_python_use_implicit_namespaces = True
 autoapi_keep_files = True
 autoapi_own_page_level = "class"
-
+autoapi_add_toctree_entry = False
 # Examples gallery customization
 nbsphinx_execute = "always"
-nbsphinx_custom_formats = {
-    ".mystnb": ["jupytext.reads", {"fmt": "mystnb"}],
-}
 
 nbsphinx_epilog = """
 ----
@@ -251,12 +231,18 @@ def get_wheelhouse_assets_dictionary():
 linkcheck_exclude_documents = ["index", "getting_started/local/index", "assets"]
 
 # -- Declare the Jinja context -----------------------------------------------
-exclude_patterns = []
-BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
+exclude_patterns = [
+    "examples/**/*.ipynb",
+    "examples/**/*.py",
+    "examples/**/*.md5",
+    "api/ansys/visualizer/index.rst",
+]
+
+BUILD_API = True
 if not BUILD_API:
     exclude_patterns.append("autoapi")
 
-BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
+BUILD_EXAMPLES = True
 if not BUILD_EXAMPLES:
     exclude_patterns.append("examples/**")
     exclude_patterns.append("examples.rst")
@@ -265,14 +251,7 @@ def get_wheelhouse_assets_dictionary():
     "main_toctree": {
         "build_api": BUILD_API,
         "build_examples": BUILD_EXAMPLES,
-    },
-    "linux_containers": {
-        "add_windows_warnings": False,
-    },
-    "windows_containers": {
-        "add_windows_warnings": True,
-    },
-    "wheelhouse-assets": {"assets": get_wheelhouse_assets_dictionary()},
+    }
 }
 
 

doc/source/contributing.rst

@@ -90,10 +90,10 @@ Build the documentation
 
 .. note::
 
-To build the documentation locally, you must run this command to install the
-documentation dependencies::
+  To build the documentation locally, you must run this command to install the
+  documentation dependencies::
 
-  pip install -e .[doc]
+    pip install -e .[doc]
 
 Then, navigate to the ``docs`` directory and run this command::
 

doc/source/index.rst

@@ -35,7 +35,7 @@ PyAnsys Visualizer is a Python package that provides a simple interface to visua
         {% if build_examples %}
         .. grid-item-card:: Examples :fa:`scroll`
             :padding: 2 2 2 2
-            :link: examples
+            :link: examples/index
             :link-type: doc
 
             Explore examples that show how to use PyAnsys Visualizer to
@@ -54,7 +54,6 @@ PyAnsys Visualizer is a Python package that provides a simple interface to visua
        api/index
        {% endif %}
        {% if build_examples %}
-       examples
+       examples/index
        {% endif %}
-       contributing
-       assets
+       contributing

doc/source/user_guide/index.rst

@@ -106,11 +106,12 @@ provides a set of methods that can be overridden so you can adapt the plotter to
 To this end, the first thing you need to do is to create a new class that inherits from the ``PlotterInterface`` class. After that, you have two
 main options to customize the plotter:
 
-* The most common need that you will have is to customize the way the objects you represent are shown in the plotter. To this end, you can override the
-``add`` and ``add_iter`` methods. These methods are called every time a new object is added to the plotter. The default implementation of this method is to add a PyVista mesh or a
-``MeshObjectPlot`` instance to the plotter. You can override this method to add your own meshes or objects to the plotter in a manner that fits the way you want to represent the meshes.
+* | The most common need that you will have is to customize the way the objects you represent are shown in the plotter. To this end, you can override the
+  | ``add`` and ``add_iter`` methods. These methods are called every time a new object is added to the plotter. The default implementation of this method is to add a PyVista mesh or a
+  | ``MeshObjectPlot`` instance to the plotter. You can override this method to add your own meshes or objects to the plotter in a manner that fits the way you want to represent the meshes.
+
+* | Another use case is the need of having custom button functionalities for your library, to, for example, hide or show certain objects. You can make use of the ``PlotterWidget`` class to
+  | add custom buttons to the plotter. This class provides an implementable interface where you can add your own buttons to the plotter.
 
-* Another use case is the need of having custom button functionalities for your library, to, for example, hide or show certain objects. You can make use of the ``PlotterWidget`` class to
-add custom buttons to the plotter. This class provides an implementable interface where you can add your own buttons to the plotter.
 
 Some practical examples of how to use the ``PlotterInterface`` class are included in some PyAnsys libraries, such as `PyAnsys Geometry <https://github.com/ansys/pyansys-geometry/pull/959>_`.

examples/00-basic-examples/README.txt

@@ -1,4 +1,4 @@
 Basic usage examples for PyAnsys Visualizer
 ===========================================
 
-These examples show some use cases for the library.
+Examples on how to use the general plotter included in the library.

examples/00-basic-examples/clipping_plane.py

@@ -42,7 +42,7 @@
 
 # Create a clipping plane
 
-clipping_plane = ClipPlane()
+clipping_plane = ClipPlane(normal=(1, 0, 0), origin=(0, 0, 0))
 
 # Add the mesh to the plotter with the clipping plane
 pl.add(mesh, clipping_plane=clipping_plane)

examples/README.txt

@@ -0,0 +1,4 @@
+Examples
+========
+
+These are some of the most common use cases that you might find while using PyAnsys Visualizer.

pyproject.toml

@@ -30,12 +30,25 @@ dependencies = [
 
 [project.optional-dependencies]
 
-tests = [
+test = [
     "pytest==7.4.4",
     "pytest-pyvista==0.1.9",
     "pytest-cov==4.1.0",
 ]
 
+docs = [
+    "ansys-sphinx-theme==0.14.0",
+    "jupyter_sphinx==0.5.3",
+    "jupytext==1.16.1",
+    "nbsphinx==0.9.3",
+    "numpydoc==1.6.0",
+    "sphinx==7.2.6",
+    "sphinx-autoapi==3.1.a2",
+    "sphinx-copybutton==0.5.2",
+    "sphinx_design==0.5.0",
+    "sphinx-jinja==2.0.2",
+]
+
 [tool.flit.module]
 name = "ansys.visualizer"
 

src/ansys/visualizer/__init__.py

@@ -20,8 +20,12 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """PyAnsys visualizer is a python package to help visualize the results of ansys simulations."""
+import pkg_resources
+
 from ansys.visualizer.interfaces.trame_gui import _HAS_TRAME, TrameVisualizer
 
+__version__ = pkg_resources.get_distribution("pyansys-visualizer").version
+
 USE_TRAME: bool = False
 DOCUMENTATION_BUILD: bool = False
 from ansys.visualizer.plotter import Plotter, PlotterInterface