Fix doc xrefs

.pre-commit-config.yaml

@@ -24,7 +24,8 @@ repos:
     rev: v1.7.5
     hooks:
       - id: docformatter
-        additional_dependencies: [tomli==2.0.1]
+        additional_dependencies: [tomli]
+        args: ["--wrap-summaries", "0"]
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.5

doc/Makefile

@@ -22,8 +22,7 @@ help:
 # Customized clean due to examples gallery
 clean:
 	rm -rf $(BUILDDIR)
-	rm -rf $(SOURCEDIR)/examples
-	find . -type d -name "_autosummary" -exec rm -rf {} +
+	rm -rf $(SOURCEDIR)/examples $(SOURCEDIR)/api
 
 # Customized pdf fov svg format images
 pdf:

doc/make.bat

@@ -34,7 +34,7 @@ goto end
 :clean
 rmdir /s /q %BUILDDIR% > /NUL 2>&1
 rmdir /s /q %SOURCEDIR%\examples > /NUL 2>&1
-for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
+rmdir /s /q %SOURCEDIR%\api > /NUL 2>&1
 goto end
 
 :help

doc/source/conf.py

@@ -229,6 +229,7 @@
 
 BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
 BUILD_EXAMPLES_LONG = True if os.environ.get("BUILD_EXAMPLES_LONG", "true") == "true" else False
+PLOT_GALLERY = True if os.environ.get("PLOT_GALLERY", "true") == "true" else False
 if BUILD_EXAMPLES is True:
     # Necessary to build examples using PyVista
     pyvista.BUILDING_GALLERY = True
@@ -267,7 +268,7 @@
         "ignore_pattern": r"\b(" + "|".join(ignore_patterns) + r")\b",
         "thumbnail_size": (350, 350),
         # Set plot_gallery to False for building docs without running examples.
-        # "plot_gallery": False,
+        "plot_gallery": PLOT_GALLERY,
     }
     print(f"sphinx_gallery_conf {sphinx_gallery_conf}")
 

doc/source/getting_started/index.rst

@@ -17,6 +17,8 @@ Starting a session
 
 There are multiple ways to start a session with the PyAdditive client.
 
+.. _ref_starting_a_local_session:
+
 Starting a local session
 ------------------------
 
@@ -236,7 +238,7 @@ System testing on localhost
 ---------------------------
 
 System testing can be done on localhost using the startup method
-described in :ref:`Starting a local session` within a Python script
+described in :ref:`ref_starting_a_local_session` within a Python script
 or Jupyter notebook. The ``examples`` folder of the PyAdditive
 repository contains script files that can be used for testing or
 converted to Jupyter notebooks using

doc/source/index.rst

@@ -3,8 +3,6 @@
    Provide any documentation specific to your online documentation
    here.
 
-.. vale off
-
 PyAdditive documentation  |version|
 ===================================
 
@@ -23,6 +21,4 @@ PyAdditive documentation  |version|
        {% endif %}
        {% if build_examples %}
        examples/gallery_examples/index
-       {% endif %}
-
-.. vale on
+       {% endif %}

examples/00_additive_single_bead.py

@@ -56,26 +56,22 @@
 ###############################################################################
 # Select material
 # ---------------
-# Select a material. You can use the
-# :meth:`materials_list() <ansys.additive.core.additive.Additive.materials_list>`
-# method to obtain a list of available materials.
+# Select a material. You can use the :meth:`~Additive.materials_list` method to
+# obtain a list of available materials.
 
 additive.materials_list()
 
 ###############################################################################
 # You can obtain the parameters for a single material by passing a name
-# from the materials list to the
-# :meth:`material() <ansys.additive.core.additive.Additive.material>`
-# method.
+# from the materials list to the :meth:`~Additive.material` method.
 
 material = additive.material("17-4PH")
 
 ###############################################################################
 # Specify machine parameters
 # --------------------------
-# Specify machine parameters by first creating an
-# :class:`AdditiveMachine <ansys.additive.core.machine.AdditiveMachine>` object
-# then assigning the desired values. All values are in SI units (m, kg, s, K)
+# Specify machine parameters by first creating an :class:`AdditiveMachine` object
+# and then assigning the desired values. All values are in SI units (m, kg, s, K)
 # unless otherwise noted.
 
 machine = AdditiveMachine()
@@ -94,8 +90,7 @@
 ###############################################################################
 # Specify inputs for single bead simulation
 # -----------------------------------------
-# Create a :class:`SingleBeadInput <ansys.additive.core.single_bead.SingleBeadInput>`
-# object containing the desired simulation parameters.
+# Create a :class:`SingleBeadInput` object containing the desired simulation parameters.
 
 input = SingleBeadInput(
     machine=machine, material=material, id="single-bead-example", bead_length=0.0012  # meters
@@ -104,12 +99,9 @@
 ###############################################################################
 # Run simulation
 # --------------
-# Use the :meth:`simulate() <ansys.additive.core.additive.Additive.simulate>`
-# method of the ``additive`` object to run the simulation. The returned object is a
-# either a :class:`SingleBeadSummary <ansys.additive.core.single_bead.SingleBeadSummary>`
-# object containing the input and a
-# :class:`MeltPool <ansys.additive.core.single_bead.MeltPool>` or a
-# :class:`SimulationError <ansys.additive.core.simulation.SimulationError>`.
+# Use the :meth:`~Additive.simulate` method of the ``additive`` object to run the simulation.
+# The returned object is either a :class:`SingleBeadSummary` object containing the input
+# and a :class:`MeltPool` or a :class:`SimulationError` object.
 
 summary = additive.simulate(input)
 if isinstance(summary, SimulationError):
@@ -118,11 +110,12 @@
 ###############################################################################
 # Plot melt pool statistics
 # -------------------------
-# Obtain a :class:`Pandas DataFrame <pandas.DataFrame>` containing the melt pool
-# statistics by using the :meth:`data_frame() <ansys.additive.core.single_bead.MeltPool.data_frame>`
-# property of the ``melt_pool`` attribute of the ``summary`` object. Use the
-# :meth:`DataFrame.plot() <pandas.DataFrame.plot>` method to plot the melt
-# pool dimensions as a function of bead length.
+# Obtain a :class:`Pandas DataFrame <pandas.DataFrame>` instance containing the melt pool
+# statistics by using the :meth:`~MeltPool.data_frame` method of the ``melt_pool``
+# attribute of the ``summary`` object. The column names for the :class:`~pandas.DataFrame`
+# instance are described in the documentation for :meth:`~MeltPool.data_frame`. Use the
+# :meth:`~pandas.DataFrame.plot` method to plot the melt pool dimensions as a function
+# of bead length.
 
 df = summary.melt_pool.data_frame().multiply(1e6)  # convert from meters to microns
 df.index *= 1e3  # convert bead length from meters to millimeters
@@ -141,18 +134,16 @@
 )
 plt.show()
 
-
 ###############################################################################
 # List melt pool statistics
 # -------------------------
 # You can show a table of the melt pool statistics by typing the name of the
 # data frame object and pressing enter. For brevity, the following code
-# uses ``head()`` so that only the first few rows are shown.
+# uses the :meth:`~pandas.DataFrame.head` method so that only the first few rows are shown.
+# Note, if running this example as a Python script, no output is shown.
 
 df.head()
 
-# .. note::
-#    If running this example as a Python script, no output is shown.
 ###############################################################################
 # Save melt pool statistics
 # -------------------------

examples/01_additive_porosity.py

@@ -40,27 +40,23 @@
 ###############################################################################
 # Select material
 # ---------------
-# Select a material. You can use the
-# :meth:`materials_list() <ansys.additive.core.additive.Additive.materials_list>`
-# method to obtain a list of available materials.
+# Select a material. You can use the :meth:`~Additive.materials_list` method to
+# obtain a list of available materials.
 
 additive.materials_list()
 
 ###############################################################################
 # You can obtain the parameters for a single material by passing a name
-# from the materials list to the
-# :meth:`material() <ansys.additive.core.additive.Additive.material>`
-# method.
+# from the materials list to the :meth:`~Additive.material` method.
 
 material = additive.material("316L")
 
 ###############################################################################
 # Specify machine parameters
 # --------------------------
-# Specify machine parameters by first creating an
-# :class:`AdditiveMachine <ansys.additive.core.machine.AdditiveMachine>` object
-# and then assigning the desired values. All values are in SI units
-# (m, kg, s, K) unless otherwise noted.
+# Specify machine parameters by first creating an :class:`AdditiveMachine` object
+# and then assigning the desired values. All values are in SI units (m, kg, s, K)
+# unless otherwise noted.
 
 machine = AdditiveMachine()
 
@@ -78,8 +74,7 @@
 ###############################################################################
 # Specify inputs for porosity simulation
 # --------------------------------------
-# Create a :class:`PorosityInput <ansys.additive.core.porosity.PorosityInput>` object
-# containing the desired simulation parameters.
+# Create a :class:`PorosityInput` object containing the desired simulation parameters.
 
 input = PorosityInput(
     machine=machine,
@@ -93,11 +88,10 @@
 ###############################################################################
 # Run simulation
 # --------------
-# Use the :meth:`simulate() <ansys.additive.core.additive.Additive.simulate>` method
-# on the ``additive`` object to run the simulation. The returned object is a
-# :class:`PorositySummary <ansys.additive.core.porosity.PorositySummary>` object
+# Use the :meth:`~Additive.simulate` method of the ``additive`` object to run the simulation.
+# The returned object is either a :class:`PorositySummary` object
 # containing the input and the relative density of the simulated sample or a
-# :class:`SimulationError <ansys.additive.core.simulation.SimulationError>`.
+# :class:`SimulationError` object.
 
 summary = additive.simulate(input)
 if isinstance(summary, SimulationError):

examples/02_additive_microstructure.py

@@ -41,25 +41,21 @@
 ###############################################################################
 # Select material
 # ---------------
-# Select a material. You can use the
-# :meth:`materials_list() <ansys.additive.core.additive.Additive.materials_list>`
-# method to obtain a list of available materials.
+# Select a material. You can use the :meth:`~Additive.materials_list` method to
+# obtain a list of available materials.
 
 additive.materials_list()
 
 ###############################################################################
 # You can obtain the parameters for a single material by passing a name
-# from the materials list to the
-# :meth:`material() <ansys.additive.core.additive.Additive.material>`
-# method.
+# from the materials list to the :meth:`~Additive.material` method.
 
 material = additive.material("17-4PH")
 
 ###############################################################################
 # Specify machine parameters
 # --------------------------
-# Specify machine parameters by first creating an
-# :class:`AdditiveMachine <ansys.additive.core.machine.AdditiveMachine>` object
+# Specify machine parameters by first creating an :class:`AdditiveMachine` object
 # and then assigning the desired values. All values are in SI units (m, kg, s, K)
 # unless otherwise noted.
 
@@ -116,10 +112,9 @@
 ###############################################################################
 # Run simulation
 # --------------
-# Use the :meth:`simulate() <ansys.additive.core.additive.Additive.simulate>` method of the
-# ``additive`` object to run the simulation. The returned object is either a
-# :class:`MicrostructureSummary <ansys.additive.core.microstructure.MicrostructureSummary>`
-# object or a :class:`SimulationError <ansys.additive.core.simulation.SimulationError>`.
+# Use the :meth:`~Additive.simulate` method of the ``additive`` object to run the simulation.
+# The returned object is either a :class:`MicrostructureSummary` object or a
+# :class:`SimulationError` object.
 
 summary = additive.simulate(input_with_thermal)
 if isinstance(summary, SimulationError):
@@ -128,11 +123,11 @@
 ###############################################################################
 # Plot results
 # ------------
-# The :class:`MicrostructureSummary <ansys.additive.core.microstructure.MicrostructureSummary>`
-# includes three VTK files, one for each of the XY, XZ, and YZ planes. Each VTK file
-# contains data sets for grain orientation, boundaries, and number. In addition,
-# :class:`MicrostructureSummary <ansys.additive.core.microstructure.MicrostructureSummary>`
+# The ``summary``` object includes three VTK files, one for each of the
+# XY, XZ, and YZ planes. Each VTK file contains data sets for grain orientation,
+# boundaries, and number. In addition, the ``summary`` object
 # includes circle equivalence data and average grain size for each plane.
+# See :class:`MicrostructureSummary` for details.
 
 from matplotlib import colors
 from matplotlib.colors import LinearSegmentedColormap as colorMap
@@ -144,7 +139,7 @@
 from ansys.additive.core import CircleEquivalenceColumnNames
 
 ###############################################################################
-# Plot grain 2D visualizations
+# Plot 2D grain visualizations
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 # Plot the planar data, read VTK data in data set objects, and create a color
 # map to use with the boundary map.
@@ -191,7 +186,7 @@ def plot_microstructure(
 plot_microstructure(xy, xz, yz, "GrainNumber", None).show(title="Grain Number")
 
 ###############################################################################
-# Plot Grain Statistics
+# Plot grain statistics
 # ^^^^^^^^^^^^^^^^^^^^^
 # Add grain statistic plots to a figure, create a figure for grain statistics,
 # and then plot the figure.