MAINT: improving docs generation (#696)

Author: RobPasMue

doc/make.bat

@@ -7,6 +7,9 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+if "%SPHINXOPTS%" == "" (
+	set SPHINXOPTS=-j auto -W --color
+)
 set SOURCEDIR=source
 set BUILDDIR=_build
 

doc/source/conf.py

@@ -79,14 +79,15 @@
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "pint": ("https://pint.readthedocs.io/en/stable", None),
-    "numpy": ("https://numpy.org/devdocs", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
-    "pyvista": ("https://docs.pyvista.org/", None),
+    "pyvista": ("https://docs.pyvista.org/version/stable", None),
     "grpc": ("https://grpc.github.io/grpc/python/", None),
-    # kept here as an example
-    # "matplotlib": ("https://matplotlib.org/stable", None),
-    "pypim": ("https://pypim.docs.pyansys.com/version/dev", None),
+    "pint": ("https://pint.readthedocs.io/en/stable", None),
+    "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.geometry.core": (f"https://geometry.docs.pyansys.com/version/{switcher_version}", None),
 }
 
 # numpydoc configuration
@@ -208,12 +209,7 @@
 # variables are the title of pdf, watermark
 latex_elements = {"preamble": latex.generate_preamble(html_title)}
 
-linkcheck_exclude_documents = ["index"]
-linkcheck_anchors_ignore_for_url = ["https://docs.pyvista.org/api/*"]
-linkcheck_ignore = [
-    "https://github.com/ansys/pyansys-geometry/*",
-    "https://geometry.docs.pyansys.com/*",
-]
+linkcheck_exclude_documents = ["index", "getting_started/creating_local_session"]
 
 # -- Declare the Jinja context -----------------------------------------------
 exclude_patterns = []
@@ -246,3 +242,17 @@ def prepare_jinja_env(jinja_env) -> None:
 
 
 autoapi_prepare_jinja_env = prepare_jinja_env
+nitpick_ignore_regex = [
+    # Ignore typing
+    (r"py:.*", r"optional"),
+    (r"py:.*", r"beartype.typing.*"),
+    (r"py:.*", r"ansys.geometry.core.typing.*"),
+    (r"py:.*", r"Real.*"),
+    (r"py:.*", r"SketchObject"),
+    # Ignore API package
+    (r"py:.*", r"ansys.api.geometry.v0.*"),
+    (r"py:.*", r"GRPC.*"),
+    (r"py:.*", r"method"),
+    # Python std lib errors
+    (r"py:obj", r"logging.PercentStyle"),
+]

doc/source/getting_started/creating_local_session.rst

@@ -39,9 +39,9 @@ either Discovery, SpaceClaim, or the Geometry service.
 For more information on the arguments accepted by the launcher methods, please refer
 to their API documentation:
 
-* :func:`launch_modeler_with_discovery() <ansys.geometry.core.connection.launcher.launch_modeler_with_discovery>`
-* :func:`launch_modeler_with_spaceclaim() <ansys.geometry.core.connection.launcher.launch_modeler_with_spaceclaim>`
-* :func:`launch_modeler_with_geometry_service() <ansys.geometry.core.connection.launcher.launch_modeler_with_geometry_service>`
+* `launch_modeler_with_discovery <../api/ansys/geometry/core/connection/launcher/index.html#launcher.launch_modeler_with_discovery>`_
+* `launch_modeler_with_spaceclaim <../api/ansys/geometry/core/connection/launcher/index.html#launcher.launch_modeler_with_spaceclaim>`_
+* `launch_modeler_with_geometry_service <../api/ansys/geometry/core/connection/launcher/index.html#launcher.launch_modeler_with_geometry_service>`_
 
 .. note::
 

doc/styles/Vocab/ANSYS/accept.txt

@@ -21,3 +21,6 @@ PyPI
 PyVista
 SciPy
 subpackage
+launch_modeler_with_discovery
+launch_modeler_with_spaceclaim
+launch_modeler_with_geometry_service

src/ansys/geometry/core/connection/conversions.py

@@ -26,7 +26,7 @@
 from ansys.api.geometry.v0.models_pb2 import Direction as GRPCDirection
 from ansys.api.geometry.v0.models_pb2 import Ellipse as GRPCEllipse
 from ansys.api.geometry.v0.models_pb2 import Frame as GRPCFrame
-from ansys.api.geometry.v0.models_pb2 import Geometries
+from ansys.api.geometry.v0.models_pb2 import Geometries as GRPCGeometries
 from ansys.api.geometry.v0.models_pb2 import Line as GRPCLine
 from ansys.api.geometry.v0.models_pb2 import Matrix as GRPCMatrix
 from ansys.api.geometry.v0.models_pb2 import Plane as GRPCPlane
@@ -35,17 +35,19 @@
 from ansys.api.geometry.v0.models_pb2 import Tessellation
 from beartype.typing import TYPE_CHECKING, List, Optional, Tuple
 
-from ansys.geometry.core.math import Frame, Matrix44, Plane, Point2D, Point3D, UnitVector3D
-from ansys.geometry.core.misc import DEFAULT_UNITS
-from ansys.geometry.core.sketch import (
-    Arc,
-    Polygon,
-    SketchCircle,
-    SketchEdge,
-    SketchEllipse,
-    SketchFace,
-    SketchSegment,
-)
+from ansys.geometry.core.math.frame import Frame
+from ansys.geometry.core.math.matrix import Matrix44
+from ansys.geometry.core.math.plane import Plane
+from ansys.geometry.core.math.point import Point2D, Point3D
+from ansys.geometry.core.math.vector import UnitVector3D
+from ansys.geometry.core.misc.measurements import DEFAULT_UNITS
+from ansys.geometry.core.sketch.arc import Arc
+from ansys.geometry.core.sketch.circle import SketchCircle
+from ansys.geometry.core.sketch.edge import SketchEdge
+from ansys.geometry.core.sketch.ellipse import SketchEllipse
+from ansys.geometry.core.sketch.face import SketchFace
+from ansys.geometry.core.sketch.polygon import Polygon
+from ansys.geometry.core.sketch.segment import SketchSegment
 
 if TYPE_CHECKING:  # pragma: no cover
     from pyvista import PolyData
@@ -117,9 +119,9 @@ def sketch_shapes_to_grpc_geometries(
     edges: List[SketchEdge],
     faces: List[SketchFace],
     only_one_curve: Optional[bool] = False,
-) -> Geometries:
+) -> GRPCGeometries:
     """
-    Convert lists of ``SketchEdge`` and ``SketchFace`` to a ``Geometries`` gRPC message.
+    Convert lists of ``SketchEdge`` and ``SketchFace`` to a ``GRPCGeometries`` message.
 
     Parameters
     ----------
@@ -129,18 +131,16 @@ def sketch_shapes_to_grpc_geometries(
         Source edge data.
     faces : List[SketchFace]
         Source face data.
-    shapes : List[BaseShape]
-        Source shape data.
     only_one_curve : bool, default: False
         Whether to project one curve of the whole set of geometries to
         enhance performance.
 
     Returns
     -------
-    Geometries
+    GRPCGeometries
         Geometry service gRPC geometries message. The unit is meters.
     """
-    geometries = Geometries()
+    geometries = GRPCGeometries()
 
     converted_sketch_edges = sketch_edges_to_grpc_geometries(edges, plane)
     geometries.lines.extend(converted_sketch_edges[0])
@@ -159,7 +159,7 @@ def sketch_shapes_to_grpc_geometries(
             geometries.arcs.extend(converted_face_edges[1])
 
     if only_one_curve:
-        one_curve_geometry = Geometries()
+        one_curve_geometry = GRPCGeometries()
         if len(geometries.lines) > 0:
             one_curve_geometry.lines.append(geometries.lines[0])
         elif len(geometries.arcs) > 0:
@@ -181,7 +181,7 @@ def sketch_edges_to_grpc_geometries(
     plane: Plane,
 ) -> Tuple[List[GRPCLine], List[GRPCArc]]:
     """
-    Convert a list of ``SketchEdge`` to a ``Geometries`` gRPC message.
+    Convert a list of ``SketchEdge`` to a ``GRPCGeometries`` gRPC message.
 
     Parameters
     ----------

src/ansys/geometry/core/connection/launcher.py

@@ -25,6 +25,7 @@
 from beartype.typing import TYPE_CHECKING, Dict, Optional
 
 from ansys.geometry.core.connection.backend import ApiVersions, BackendType
+from ansys.geometry.core.connection.client import MAX_MESSAGE_LENGTH
 from ansys.geometry.core.connection.defaults import DEFAULT_PIM_CONFIG, DEFAULT_PORT
 from ansys.geometry.core.connection.local_instance import (
     _HAS_DOCKER,
@@ -33,7 +34,7 @@
 )
 from ansys.geometry.core.connection.product_instance import prepare_and_start_backend
 from ansys.geometry.core.logger import LOG as logger
-from ansys.geometry.core.misc import check_type
+from ansys.geometry.core.misc.checks import check_type
 
 try:
     import ansys.platform.instancemanagement as pypim
@@ -42,7 +43,6 @@
 except ModuleNotFoundError:  # pragma: no cover
     _HAS_PIM = False
 
-from ansys.geometry.core.connection.client import MAX_MESSAGE_LENGTH
 
 if TYPE_CHECKING:  # pragma: no cover
     from ansys.geometry.core.modeler import Modeler
@@ -61,7 +61,7 @@ def launch_modeler(**kwargs: Optional[Dict]) -> "Modeler":
 
     Returns
     -------
-    ansys.geometry.core.Modeler
+    ansys.geometry.core.modeler.Modeler
         Pythonic interface for geometry modeling.
 
     Examples
@@ -207,7 +207,7 @@ def launch_modeler_with_discovery_and_pimlight(version: Optional[str] = None) ->
 
     Returns
     -------
-    ansys.geometry.core.Modeler
+    ansys.geometry.core.modeler.Modeler
         Instance of Modeler.
     """
     return _launch_pim_instance(
@@ -236,7 +236,7 @@ def launch_modeler_with_geometry_service_and_pimlight(version: Optional[str] = N
 
     Returns
     -------
-    ansys.geometry.core.Modeler
+    ansys.geometry.core.modeler.Modeler
         Instance of Modeler.
     """
     return _launch_pim_instance(
@@ -265,7 +265,7 @@ def launch_modeler_with_spaceclaim_and_pimlight(version: Optional[str] = None) -
 
     Returns
     -------
-    ansys.geometry.core.Modeler
+    ansys.geometry.core.modeler.Modeler
         Instance of Modeler.
     """
     return _launch_pim_instance(
@@ -375,7 +375,7 @@ def launch_modeler_with_discovery(
 
     Parameters
     ----------
-    product_version: ``int``, optional
+    product_version: int, optional
         The product version to be started. Goes from v23.2.1 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -398,7 +398,7 @@ def launch_modeler_with_discovery(
             3: Error
 
         The default is ``2`` (Warning).
-    api_version: ``ApiVersions``, optional
+    api_version: ApiVersions, optional
         The backend's API version to be used at runtime. Goes from API v21 to
         the latest. Default is ``ApiVersions.LATEST``.
     timeout : int, optional
@@ -467,7 +467,7 @@ def launch_modeler_with_spaceclaim(
 
     Parameters
     ----------
-    product_version: ``int``, optional
+    product_version: int, optional
         The product version to be started. Goes from v23.2.1 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -490,7 +490,7 @@ def launch_modeler_with_spaceclaim(
             3: Error
 
         The default is ``2`` (Warning).
-    api_version: ``ApiVersions``, optional
+    api_version: ApiVersions, optional
         The backend's API version to be used at runtime. Goes from API v21 to
         the latest. Default is ``ApiVersions.LATEST``.
     timeout : int, optional

src/ansys/geometry/core/connection/local_instance.py

@@ -28,7 +28,7 @@
 from beartype.typing import Optional, Tuple, Union
 
 try:
-    import docker
+    from docker.client import DockerClient
     from docker.errors import APIError, ContainerError, ImageNotFound
     from docker.models.containers import Container
 
@@ -97,7 +97,7 @@ class LocalDockerInstance:
         OS.
     """
 
-    __DOCKER_CLIENT__: "docker.DockerClient" = None
+    __DOCKER_CLIENT__: "DockerClient" = None
     """
     Docker client class variable. The default is ``None``, in which case lazy
     initialization is used.
@@ -110,7 +110,7 @@ class LocalDockerInstance:
 
     @staticmethod
     @_docker_python_available
-    def docker_client() -> "docker.DockerClient":
+    def docker_client() -> "DockerClient":
         """
         Get the initialized ``__DOCKER_CLIENT__`` object.
 
@@ -121,11 +121,11 @@ def docker_client() -> "docker.DockerClient":
 
         Returns
         -------
-        docker.DockerClient
+        ~docker.client.DockerClient
             Initialized Docker client.
         """
         if not LocalDockerInstance.__DOCKER_CLIENT__:
-            LocalDockerInstance.__DOCKER_CLIENT__ = docker.from_env()
+            LocalDockerInstance.__DOCKER_CLIENT__ = DockerClient.from_env()
 
         return LocalDockerInstance.__DOCKER_CLIENT__
 

src/ansys/geometry/core/designer/beam.py

@@ -23,8 +23,10 @@
 
 from beartype.typing import TYPE_CHECKING, Union
 
-from ansys.geometry.core.math import Point3D, UnitVector3D
-from ansys.geometry.core.misc import Distance, check_type
+from ansys.geometry.core.math.point import Point3D
+from ansys.geometry.core.math.vector import UnitVector3D
+from ansys.geometry.core.misc.checks import check_type
+from ansys.geometry.core.misc.measurements import Distance
 
 if TYPE_CHECKING:  # pragma: no cover
     from ansys.geometry.core.designer.component import Component

src/ansys/geometry/core/designer/body.py

@@ -43,26 +43,28 @@
 from beartype.typing import TYPE_CHECKING, List, Optional, Tuple, Union
 from pint import Quantity
 
-from ansys.geometry.core.connection import (
-    GrpcClient,
+from ansys.geometry.core.connection.client import GrpcClient
+from ansys.geometry.core.connection.conversions import (
     sketch_shapes_to_grpc_geometries,
     tess_to_pd,
     unit_vector_to_grpc_direction,
 )
 from ansys.geometry.core.designer.edge import CurveType, Edge
 from ansys.geometry.core.designer.face import Face, SurfaceType
 from ansys.geometry.core.errors import protect_grpc
-from ansys.geometry.core.materials import Material
-from ansys.geometry.core.math import IDENTITY_MATRIX44, Matrix44, UnitVector3D
-from ansys.geometry.core.misc import DEFAULT_UNITS, Distance, check_type
-from ansys.geometry.core.sketch import Sketch
+from ansys.geometry.core.materials.material import Material
+from ansys.geometry.core.math.constants import IDENTITY_MATRIX44
+from ansys.geometry.core.math.matrix import Matrix44
+from ansys.geometry.core.math.vector import UnitVector3D
+from ansys.geometry.core.misc.checks import check_type
+from ansys.geometry.core.misc.measurements import DEFAULT_UNITS, Distance
+from ansys.geometry.core.sketch.sketch import Sketch
 from ansys.geometry.core.typing import Real
 
 if TYPE_CHECKING:  # pragma: no cover
     from pyvista import MultiBlock, PolyData
 
     from ansys.geometry.core.designer.component import Component
-    from ansys.geometry.core.designer.design import MidSurfaceOffsetType
 
 
 @unique
@@ -178,7 +180,7 @@ def add_midsurface_thickness(self, thickness: Quantity) -> None:
 
         Parameters
         ----------
-        thickness : Quantity
+        thickness : ~pint.Quantity
             Thickness to assign.
 
         Notes
@@ -308,7 +310,7 @@ def translate(self, direction: UnitVector3D, distance: Union[Quantity, Distance,
         ----------
         direction: UnitVector3D
             Direction of the translation.
-        distance: Union[Quantity, Distance, Real]
+        distance: Union[~pint.Quantity, Distance, Real]
             Distance (magnitude) of the translation.
 
         Returns
@@ -417,7 +419,7 @@ def plot(
             is used.
         **plotting_options : dict, default: None
             Keyword arguments for plotting. For allowable keyword arguments, see the
-            :func:`pyvista.Plotter.add_mesh` method.
+            :meth:`Plotter.add_mesh <pyvista.Plotter.add_mesh>` method.
 
         Examples
         --------