Fix api doc issues

doc/source/conf.py

@@ -131,6 +131,7 @@
     "pypim": ("https://pypim.docs.pyansys.com/version/stable", None),
     "panel": ("https://panel.holoviz.org/", None),
     "ansys.additive.core": (f"https://additive.docs.pyansys.com/version/{switcher_version}", None),
+    "grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
 # List of patterns, relative to source directory, that match files and

doc/source/contributing.rst

@@ -0,0 +1,89 @@
+.. _ref_contribute:
+
+##########
+Contribute
+##########
+
+Overall guidance on contributing to a PyAnsys library appears in the
+`Contributing <https://dev.docs.pyansys.com/how-to/contributing.html>`_ topic
+in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
+with this guide before attempting to contribute to PyAdditive.
+
+The following contribution information is specific to PyAdditive.
+
+Clone the repository
+--------------------
+
+To clone and install the latest PyAdditive release in development mode, run
+these commands:
+
+.. code::
+
+    git clone https://github.com/ansys/pyadditive
+    cd pyadditive
+    python -m pip install --upgrade pip
+    pip install -e .
+
+
+Post issues
+-----------
+
+Use the `PyAdditive Issues <https://github.com/ansys/pyadditive/issues>`_
+page to submit questions, report bugs, and request new features. When possible, you
+should use these issue templates:
+
+* Bug, problem, error: For filing a bug report
+* Documentation error: For requesting modifications to the documentation
+* Adding an example: For proposing a new example
+* New feature: For requesting enhancements to the code
+
+If your issue does not fit into one of these template categories, you can click
+the link for opening a blank issue.
+
+To reach the project support team, email `pyansys.core@ansys.com <pyansys.core@ansys.com>`_.
+
+View documentation
+------------------
+
+Documentation for the latest stable release of PyAdditive is hosted at
+`PyAdditive Documentation <https://additive.docs.pyansys.com>`_.
+
+In the upper right corner of the documentation's title bar, there is an option
+for switching from viewing the documentation for the latest stable release
+to viewing the documentation for the development version or previously
+released versions.
+
+Adhere to code style
+--------------------
+
+PyAdditive follows the PEP8 standard as outlined in
+`PEP 8 <https://dev.docs.pyansys.com/coding-style/pep8.html>`_ in
+the `PyAnsys Developer's Guide <https://dev.docs.pyansys.com/>`_
+and implements style checking using `pre-commit <https://pre-commit.com/>`_.
+
+To ensure your code meets minimum code styling standards, run these commands::
+
+  pip install pre-commit
+  pre-commit run --all-files
+
+You can also install this as a `git` pre-commit hook by running this command::
+
+  pre-commit install
+
+This way, it's not possible for you to push code that fails the style checks::
+
+  $ pre-commit install
+  $ git commit -am "added my cool feature"
+  black....................................................................Passed
+  blacken-docs.............................................................Passed
+  isort....................................................................Passed
+  flake8...................................................................Passed
+  docformatter.............................................................Passed
+  codespell................................................................Passed
+  pydocstyle...............................................................Passed
+  check for merge conflicts................................................Passed
+  debug statements (python)................................................Passed
+  check yaml...............................................................Passed
+  trim trailing whitespace.................................................Passed
+  Add License Headers......................................................Passed
+  Validate GitHub Workflows................................................Passed

doc/source/index.rst

@@ -21,4 +21,5 @@ PyAdditive documentation  |version|
        {% endif %}
        {% if build_examples %}
        examples/gallery_examples/index
-       {% endif %}
+       {% endif %}
+       contributing

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi"
 [project]
 # Check https://flit.readthedocs.io/en/latest/pyproject_toml.html for all available sections
 name = "ansys-additive-core"
-version = "0.17.dev1"
+version = "0.17.dev2"
 description = "A Python client for the Ansys Additive service"
 readme = "README.rst"
 requires-python = ">=3.9,<4"
@@ -65,7 +65,7 @@ tests = [
 ]
 
 doc = [
-    "ansys-sphinx-theme==0.12.4",
+    "ansys-sphinx-theme==0.12.5",
     "enum-tools==0.11.0",
     "jupyter_sphinx==0.4.0",
     "matplotlib==3.8.1",

src/ansys/additive/core/additive.py

@@ -42,57 +42,44 @@
 from ansys.additive.core.download import download_file
 from ansys.additive.core.material import AdditiveMaterial
 from ansys.additive.core.material_tuning import MaterialTuningInput, MaterialTuningSummary
-from ansys.additive.core.microstructure import MicrostructureSummary
+from ansys.additive.core.microstructure import MicrostructureInput, MicrostructureSummary
 import ansys.additive.core.misc as misc
-from ansys.additive.core.porosity import PorositySummary
+from ansys.additive.core.porosity import PorosityInput, PorositySummary
 from ansys.additive.core.progress_logger import ProgressLogger
 from ansys.additive.core.server_connection import ServerConnection
 from ansys.additive.core.simulation import SimulationError
-from ansys.additive.core.single_bead import SingleBeadSummary
+from ansys.additive.core.single_bead import SingleBeadInput, SingleBeadSummary
 from ansys.additive.core.thermal_history import ThermalHistoryInput, ThermalHistorySummary
 
 
 class Additive:
-    """Provides the client interface to the Additive service.
-
-    You can connect to the Additive server using one of the following
-    methods. The methods are listed in order of precedence.
-        1. If ``channel`` is provided, use it to connect to the server.
-        2. If ``host``, and optionally ``port``, are provided, connect to the server at ``host:port``.
-        3. If running in a :class:`PyPIM <ansys.platform.instancemanagement.pypim>`-
-        enabled cloud environment, launch and connect to an ``additive`` service.
-        4. Use the value of the ``ANSYS_ADDITIVE_ADDRESS`` environment variable if it is defined.
-        The value uses the format ``host:port``.
-        5. Attempt to start the server on localhost and connect to it. For this to work,
-        the Additive portion of the Ansys Structures package from the Ansys unified installation
-        must be installed.
-
+    """Provides the client interface to one or more Additive services.
 
     Parameters
     ----------
     server_connections: list[str, grpc.Channel], None
         List of connection definitions for servers. The list may be a combination of strings and
-        connected ``grpc.Channel``s. Strings use the format ``host:port`` to specify
-        the server IPv4 address.
-    channel: grpc.Channel, None
-        gRPC channel connection to use for communicating with the server. If None, a connection will be
-        established using the host and port parameters. Ignored if ``server_channels``
-        is not ``None``.
-    host: str, None
-        Host name or IPv4 address of the server. Ignored if ``server_channels`` or ``channel``
-        is not ``None``.
-    port: int
-        Port number to use when connecting to the server. Defaults to 50052.
-    nservers: int
-        Number of Additive servers to start and connect to. If running in a
-        :class:`PyPIM <ansys.platform.instancemanagement.pypim>` enabled environment,
-        ``nservers`` ``additive`` services will be started. If running on localhost,
+        connected :class:`grpc.Channel <grpc.Channel>` objects. Strings use the format
+        ``host:port`` to specify the server IPv4 address.
+    channel: grpc.Channel, default: None
+        gRPC channel connection to use for communicating with the server. If the
+        default ``None`` is used, a connection is established using the host and port
+        parameters. This parameter is ignored if the ``server_connections`` parameter
+        is other than ``None``.
+    host: str, default: None
+        Host name or IPv4 address of the server. This parameter is ignored if the
+        ``server_channels`` or ``channel`` parameters is other than ``None``.
+    port: int, default: 50052
+        Port number to use when connecting to the server.
+    nservers: int, default: 1
+        Number of Additive servers to start and connect to.
         ``nservers`` instances of Additive server will be started. For this to work,
-        the Additive portion of the Ansys Structures package must be installed. Ignored if
-        ``server_connections``, ``channel``, or ``host`` is not ``None``.
-    log_level: str
+        the Additive portion of the Ansys Structures package must be installed.
+        This parameter is ignored if the ``server_connections``, ``channel``, or ``host``
+        parameter is other than ``None``.
+    log_level: str, default: "INFO"
         Minimum severity level of messages to log.
-    log_file: str
+    log_file: str, default: ""
         File name to write log messages to.
     """
 
@@ -184,22 +171,31 @@ def about(self) -> None:
             for server in self._servers:
                 print(server.status())
 
-    def simulate(self, inputs):
-        """Execute an additive simulation.
+    def simulate(
+        self,
+        inputs: SingleBeadInput | PorosityInput | MicrostructureInput | ThermalHistoryInput | list,
+    ) -> (
+        SingleBeadSummary
+        | PorositySummary
+        | MicrostructureSummary
+        | ThermalHistorySummary
+        | SimulationError
+        | list
+    ):
+        """Execute additive simulations.
 
         Parameters
         ----------
-        inputs: :class:`SingleBeadInput`, :class:`PorosityInput`,
-        :class:`MicrostructureInput`, :class:`ThermalHistoryInput`
-        or a list of these input types
-            Parameters to use for simulations.
+        inputs: SingleBeadInput, PorosityInput, MicrostructureInput, ThermalHistoryInput, list
+            Parameters to use for simulations. A list of inputs may be provided to execute multiple
+            simulations.
 
         Returns
         -------
-        :class:`SingleBeadSummary`, :class:`PorositySummary`,
-        :class:`MicrostructureSummary`, :class:`ThermalHistorySummary`,
-        :class:`SimulationError`, or, if a list of inputs was provided,
-        a list of these types.
+        SingleBeadSummary, PorositySummary, MicrostructureSummary, ThermalHistorySummary, SimulationError,
+        list
+            One or more summaries of simulation results. If a list of inputs is provided, a
+            list is returned.
         """
         if type(inputs) is not list:
             return self._simulate(inputs, self._servers[0], show_progress=True)
@@ -236,7 +232,12 @@ def simulate(self, inputs):
         print("")
         return summaries
 
-    def _simulate(self, input, server: ServerConnection, show_progress: bool = False):
+    def _simulate(
+        self,
+        input: SingleBeadInput | PorosityInput | MicrostructureInput | ThermalHistoryInput,
+        server: ServerConnection,
+        show_progress: bool = False,
+    ):
         """Execute a single simulation.
 
         Parameters
@@ -252,10 +253,8 @@ def _simulate(self, input, server: ServerConnection, show_progress: bool = False
 
         Returns
         -------
-        One of the follow summary objects:
-        :class:`SingleBeadSummary`, :class:`PorositySummary`,
-        :class:`MicrostructureSummary`, :class:`ThermalHistorySummary`,
-        :class:`SimulationError`
+        SingleBeadSummary, PorositySummary, MicrostructureSummary, ThermalHistorySummary,
+        SimulationError
         """
         logger = None
         if show_progress:
@@ -328,18 +327,18 @@ def load_material(
             Name of the JSON file containing material parameters. For more information, see
             `Create Material Parameters File (.json)
             <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v232/en/add_beta/add_print_udm_tool_create_tables.html>`_
-            in the *Additiivate Manufacturing Beta Features* documentation.
+            in the *Additive Manufacturing Beta Features* documentation.
         thermal_lookup_file: str
             Name of the CSV file containing the lookup table for thermal dependent properties.
             For more information, see `Create Material Lookup File (.csv)
             <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v232/en/add_beta/add_print_udm_create_mat_lookup.html>`_
-            in the *Additiivate Manufacturing Beta Features* documentation.
+            in the *Additive Manufacturing Beta Features* documentation.
         characteristic_width_lookup_file: str
             Name of the CSV file containing the lookup table for characteristic melt pool width. For
             more information, see
             `Find Characteristic Width Values and Generate Characteristic Width File (.csv)
             <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v232/en/add_beta/add_print_udm_tool_find_cw.html>`_
-            in the *Additiivate Manufacturing Beta Features* documentation.
+            in the *Additive Manufacturing Beta Features* documentation.
         """
         material = AdditiveMaterial()
         material._load_parameters(parameters_file)
@@ -352,6 +351,15 @@ def tune_material(
     ) -> MaterialTuningSummary:
         """Tune a custom material for use with additive simulations.
 
+        This method performs the same function as the Material Tuning Tool
+        described in
+        `Find Simulation Parameters to Match Simulation to Experiments
+        <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v232/en/add_beta/add_print_udm_tool_match_sim_to_exp.html>`_.
+        It is used for one step in the material tuning process. The other steps
+        are described in
+        `Chapter 2: Material Tuning Tool (Beta) to Create User Defined Materials
+        <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v232/en/add_beta/add_science_BETA_material_tuning_tool.html>`_.
+
         Parameters
         ----------
         input: MaterialTuningInput
@@ -361,7 +369,7 @@ def tune_material(
         -------
         MaterialTuningSummary
             Summary of material tuning.
-        """
+        """  # noqa: E501
         if input.id == "":
             input.id = misc.short_uuid()
         if out_dir == USER_DATA_PATH:

src/ansys/additive/core/examples/__init__.py

@@ -28,5 +28,4 @@
     download_custom_material,
     download_material_tuning_input,
     download_small_wedge_slm_build_file,
-    get_ext,
 )

src/ansys/additive/core/examples/downloads.py

@@ -36,12 +36,6 @@
 CUSTOM_MATERIAL_FOLDER = "pyadditive/custom_material_data"
 
 
-def get_ext(filename):
-    """Extract the extension of the filename."""
-    ext = os.path.splitext(filename)[1].lower()
-    return ext
-
-
 def delete_downloads():
     """Delete all downloaded examples to free space or update the files."""
     shutil.rmtree(EXAMPLES_PATH)
@@ -59,6 +53,7 @@ def decompress(filename, subdir=None) -> str:
     subdir : str, None
         Name of the subdirectory of the ``examples`` directory
         to extract the ZIP file contents to. The default is ``None``.
+
     Returns
     -------
     str
@@ -131,11 +126,11 @@ class MaterialTuningExampleInputFiles:
     experiment_data_file : str
         Path to the experiment data file.
     material_parameters_file : str
-            Path to the material parameters file.
-        thermal_properties_lookup_file : str
-            Path to the thermal properties lookup file.
-        characteristic_width_lookup_file : str
-            Path to the characteristic width lookup file.
+        Path to the material parameters file.
+    thermal_properties_lookup_file : str
+        Path to the thermal properties lookup file.
+    characteristic_width_lookup_file : str
+        Path to the characteristic width lookup file.
     """
 
     def __init__(