From a73e77952255147a33e216447baaeb73309ed7f2 Mon Sep 17 00:00:00 2001 From: Michael Jackson Date: Tue, 30 Jan 2024 18:21:33 -0500 Subject: [PATCH] Reduced or fix sphinx generation warnings Signed-off-by: Michael Jackson --- wrapping/python/docs/source/Developer_API.rst | 70 ++++++++++--------- .../python/docs/source/ReleaseNotes_110.rst | 2 +- wrapping/python/docs/source/User_API.rst | 38 +++++----- .../source/Writing_A_New_Python_Filter.rst | 6 +- wrapping/python/docs/source/conf.py | 2 +- 5 files changed, 64 insertions(+), 54 deletions(-) diff --git a/wrapping/python/docs/source/Developer_API.rst b/wrapping/python/docs/source/Developer_API.rst index 2550a995b5..c7a9644e3a 100644 --- a/wrapping/python/docs/source/Developer_API.rst +++ b/wrapping/python/docs/source/Developer_API.rst @@ -32,8 +32,8 @@ General Parameters - **Description**: A brief description or help text for the parameter. This text is intended to guide the user in understanding the purpose of the parameter and how to use it. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` - - **Description**: The default value for the parameter. For the `ArrayCreationParameter`, this is a :ref:`DataPath` object that points to the location within the data structure where the data array will be created. + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default value for the parameter. For the `ArrayCreationParameter`, this is a :ref:`DataPath ` object that points to the location within the data structure where the data array will be created. - **Type**: `DataPath` Usage @@ -73,7 +73,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default DataPath pointing to the array to be selected. - **Type**: `DataPath` @@ -190,7 +190,7 @@ General Parameters This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() ` filter. - :ivar array_path: The :ref:`DataPath` to the array to use for this ArrayThreshold + :ivar array_path: The :ref:`DataPath ` to the array to use for this ArrayThreshold :ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!=" :ivar value: Numerical Value. The value for the comparison @@ -244,7 +244,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default DataPath pointing to the Attribute Matrix to be selected. - **Type**: `DataPath` @@ -329,7 +329,7 @@ General Parameters .. py:class:: CalculatorParameter.ValueType - :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray` that will be used in the equations + :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations :ivar equation: String. The equation that will be evaluated :ivar units: cx.CalculatorParameter.AngleUnits.Radians or cx.CalculatorParameter.AngleUnits.Degrees @@ -351,7 +351,7 @@ General Parameters - **Description**: The default value or expression for the calculator parameter. - **Type**: `CalculatorParameter.ValueType` - **Internal Data**: The values that are contained within the CalculatorParameter.ValueType. - - selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray` that will be used in the equations. + - selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations. - equation: String. The equation that will be evaluated. - units: sx.CalculatorParameter.AngleUnits.Radians or sx.CalculatorParameter.AngleUnits.Degrees @@ -449,7 +449,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default DataPath for the data group to be created. - **Type**: `DataPath` @@ -489,7 +489,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default DataPath pointing to the data group to be selected. - **Type**: `DataPath` @@ -557,7 +557,7 @@ General Parameters Description ~~~~~~~~~~~ - The ``DataPathSelectionParameter`` is used for selecting a :ref:`DataPath` to a data object within the :ref:`DataStructure`. + The ``DataPathSelectionParameter`` is used for selecting a :ref:`DataPath ` to a data object within the :ref:`DataStructure`. Inputs ~~~~~~ @@ -573,7 +573,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default DataPath to be selected. - **Type**: `DataPath` @@ -716,7 +716,7 @@ General Parameters - **Type**: `Dream3dImportParameter.ImportData` - **Internal Data**: - **file_path**: Path to the .dream3d file on the file system - - **data_paths**: List of :ref:`DataPath` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. + - **data_paths**: List of :ref:`DataPath ` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. Usage ~~~~~~ @@ -734,7 +734,7 @@ General Parameters .. py:class:: DynamicTableParameter Declarations - ~~~~~~~~~~~ + ~~~~~~~~~~~~ .. code-block:: python DynamicTableParameter(name: str, human_name: str, help_text: str, default_value: List[List[float]], table_info: DynamicTableInfo) @@ -1115,7 +1115,7 @@ General Parameters - **Description**: A brief description or help text for the parameter. - **Type**: string (str) - - ``default_value`` : :ref:`DataPath` + - ``default_value`` : :ref:`DataPath ` - **Description**: The default path to the geometry data. - **Type**: `DataPath` @@ -1188,7 +1188,7 @@ General Parameters a number of member variables that need to be set correctly before passing it into the filter parameter as the default value. - ``column_data_types`` : List[DataType] - - **Description**: The data types of the columns in the CSV file. Indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray`. + - **Description**: The data types of the columns in the CSV file. Indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray `. - **Type**: List of :ref:`cx.DataType` - ``consecutive_delimiters`` : bool @@ -1377,7 +1377,7 @@ General Parameters - ``input_file`` : str - **Description**: The file path to the input HDF5 file. - ``parent`` : Optional[DataPath] - - **Description**: The :ref:`DataPath` object to a parent group to create the :ref:`DataArray`s into. If left blank, the :ref:`DataArray` will be created at the top level of the :ref:`DataStructure`. + - **Description**: The :ref:`DataPath ` object to a parent group to create the :ref:`DataArrays ` into. If left blank, the :ref:`DataArray ` will be created at the top level of the :ref:`DataStructure`. Usage ~~~~~~ @@ -1468,7 +1468,7 @@ General Parameters Description ~~~~~~~~~~~ - This parameter represents a list of :ref:`DataPath` objects. The end point of each :ref:`DataPath` object can be any object in the :ref:`DataStructure` + This parameter represents a list of :ref:`DataPath ` objects. The end point of each :ref:`DataPath ` object can be any object in the :ref:`DataStructure` Inputs ~~~~~~ @@ -1638,8 +1638,9 @@ General Parameters Numerical Parameters -------------------- - Declarations - ~~~~~~~~~~~ +Declarations +~~~~~~~~~~~~ + .. code-block:: python class Int8Parameter(IParameter): @@ -1672,13 +1673,13 @@ Numerical Parameters class Float64Parameter(IParameter): def __init__(self, name: str, human_name: str, help_text: str, default_value: float) -> None: ... - Description - ~~~~~~~~~~~ +Description +~~~~~~~~~~~ This group of parameters wrap a specific native C++ numeric type and can be used to add integer/float inputs to a filter. Their default values can be instantiated using standard python integers or decimal values. - Inputs - ~~~~~~ +Inputs +~~~~~~ - ``name`` : str - **Description**: The programmatic name of the parameter. - **Type**: string (str) @@ -1695,8 +1696,8 @@ Numerical Parameters - **Description**: The default value for the parameter, expected to be within the range of the chosen float or integer type. - **Type**: Integer or Float - Usage - ~~~~~~ +Usage +~~~~~~ .. code-block:: python @@ -1706,10 +1707,11 @@ Numerical Parameters params.insert(sx.Int32Parameter('int32_key', 'Int32Parameter', 'The 2nd parameter', 0)) Numerical Vector Parameters --------------------- +--------------------------- + +Declarations +~~~~~~~~~~~~ - Declarations - ~~~~~~~~~~~ .. code-block:: python class VectorInt8Parameter(IParameter): @@ -1772,13 +1774,13 @@ Numerical Vector Parameters @overload def __init__(self, name: str, human_name: str, help_text: str, default_value: List[float], names: List[str]) -> None: ... - Description - ~~~~~~~~~~~ +Description +~~~~~~~~~~~ This group of parameters can be used to gather more than a single scalar value from the user. For example, an Origin for an Image Geometry or the dimensions of a DataArray. It is represented as a list of numerical values. - Inputs - ~~~~~~ +Inputs +~~~~~~ - ``name`` : str - **Description**: The programmatic name of the parameter. - **Type**: string (str) @@ -1799,8 +1801,8 @@ Numerical Vector Parameters - **Description**: The list of names that describe each value in the vector. - **Type**: List of strings - Usage - ~~~~~~ +Usage +~~~~~~ .. code-block:: python diff --git a/wrapping/python/docs/source/ReleaseNotes_110.rst b/wrapping/python/docs/source/ReleaseNotes_110.rst index b8b0ba6d39..b71ceb1a2e 100644 --- a/wrapping/python/docs/source/ReleaseNotes_110.rst +++ b/wrapping/python/docs/source/ReleaseNotes_110.rst @@ -10,7 +10,7 @@ Version 1.1.0 API Additions 1.1.0 ^^^^^^^^^^^^^^^^^^^ -- DataPath: A :ref:`DataPath` object can now be constructed with a "/" separated string in addition to a list of strings. +- DataPath: A :ref:`DataPath ` object can now be constructed with a "/" separated string in addition to a list of strings. .. code:: python diff --git a/wrapping/python/docs/source/User_API.rst b/wrapping/python/docs/source/User_API.rst index ce3b770315..8fabb5f3e7 100644 --- a/wrapping/python/docs/source/User_API.rst +++ b/wrapping/python/docs/source/User_API.rst @@ -1,6 +1,9 @@ API for Users ============== +Error & Warning Reporting +-------------------------- + .. _Result: .. py:class:: Result @@ -26,7 +29,8 @@ General Parameters .. _ArrayCreationParameter: .. py:class:: ArrayCreationParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of where + + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of where the DataArray will be created. .. code:: python @@ -36,7 +40,7 @@ General Parameters .. _ArraySelectionParameter: .. py:class:: ArraySelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of where + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of where the DataArray will be read. .. code:: python @@ -62,7 +66,7 @@ General Parameters This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() ` filter. - :ivar array_path: The :ref:`DataPath` to the array to use for this ArrayThreshold + :ivar array_path: The :ref:`DataPath ` to the array to use for this ArrayThreshold :ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!=" :ivar value: Numerical Value. The value for the comparison @@ -92,7 +96,7 @@ General Parameters .. _AttributeMatrixSelectionParameter: .. py:class:: AttributeMatrixSelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a selected AttributeMatrix. + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a selected AttributeMatrix. .. code:: python @@ -114,7 +118,7 @@ General Parameters .. py:class:: CalculatorParameter.ValueType - :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray` that will be used in the equations + :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations :ivar equation: String. The equation that will be evaluated :ivar units: cx.CalculatorParameter.AngleUnits.Radians or cx.CalculatorParameter.AngleUnits.Degrees @@ -144,7 +148,7 @@ General Parameters .. _DataGroupCreationParameter: .. py:class:: DataGroupCreationParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be created + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be created by the filter. .. code:: python @@ -154,7 +158,7 @@ General Parameters .. _DataGroupSelectionParameter: .. py:class:: DataGroupSelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be used in the filter. + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be used in the filter. .. code:: python @@ -172,7 +176,7 @@ General Parameters .. _DataPathSelectionParameter: .. py:class:: DataPathSelectionParameter - This parameter holds a :ref:`DataPath` object that represents an object within the :ref:`DataStructure`. + This parameter holds a :ref:`DataPath ` object that represents an object within the :ref:`DataStructure`. .. code:: python @@ -217,7 +221,7 @@ General Parameters The ImportData object has 2 member variables that can be set. :ivar file_path: Path to the .dream3d file on the file system - :ivar data_paths: List of :ref:`DataPath` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. + :ivar data_paths: List of :ref:`DataPath ` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. .. code:: python @@ -381,7 +385,7 @@ General Parameters .. _GeometrySelectionParameter: .. py:class:: GeometrySelectionParameter - This parameter represents the :ref:`DataPath` to a valid :ref:`simplnx.Geometry() ` + This parameter represents the :ref:`DataPath ` to a valid :ref:`simplnx.Geometry() ` .. _ReadCSVDataParameter: .. py:class:: ReadCSVDataParameter @@ -408,8 +412,8 @@ General Parameters :ivar start_import_row: Int. What line number does the data start on. ONE (1) Based numbering scheme. :ivar delimiters: List[string]. List of delimiters that will be used to separate the lines of the file into columns. :ivar consecutive_delimiters: Bool. Should consecutive delimiters be counted as a single delimiter. - :ivar custom_headers: List[string]. If the file does not have headers, this is a list of string values, 1 per column of data, that will also become the names of the created :ref:`DataArray`. - :ivar data_types: List[:ref:`cx.DataType`]. The DataType, one per column, that indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray`. + :ivar custom_headers: List[string]. If the file does not have headers, this is a list of string values, 1 per column of data, that will also become the names of the created :ref:`DataArray `. + :ivar data_types: List[:ref:`cx.DataType`]. The DataType, one per column, that indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray `. :ivar skipped_array_mask: List[bool]. Booleans, one per column, that indicate whether or not to skip importing each created :ref:`DataArray `. :ivar tuple_dims: List[int]. The tuple dimensions for the created :ref:`DataArrays `. :ivar headers_line: Int. The line number of the file that has the headers listed on a single line. ONE (1) based indexing. @@ -498,7 +502,7 @@ General Parameters :ivar input_file: A "PathLike" value to the HDF5 file on the file system :ivar datasets: list[ReadHDF5DatasetParameter.DatasetImportInfo, ....] - :ivar parent: Optional: The :ref:`DataPath` object to a parente group to create the :ref:`DataArray` into. If left blank the :ref:`DataArray` will be created at the top level of the :ref:`DataStructure` + :ivar parent: Optional: The :ref:`DataPath ` object to a parente group to create the :ref:`DataArray ` into. If left blank the :ref:`DataArray ` will be created at the top level of the :ref:`DataStructure` .. py:class:: ReadHDF5DatasetParameter.DatasetImportInfo @@ -533,8 +537,8 @@ General Parameters .. _MultiArraySelectionParameter: .. py:class:: MultiArraySelectionParameter - This parameter represents a list of :ref:`DataPath` objects where each :ref:`DataPath` object - points to a :ref:`DataArray` + This parameter represents a list of :ref:`DataPath ` objects where each :ref:`DataPath ` object + points to a :ref:`DataArray ` .. code:: python @@ -543,7 +547,7 @@ General Parameters .. _MultiPathSelectionParameter: .. py:class:: MultiPathSelectionParameter - This parameter represents a list of :ref:`DataPath` objects. The end point of each :ref:`DataPath` + This parameter represents a list of :ref:`DataPath ` objects. The end point of each :ref:`DataPath ` object can be any object in the :ref:`DataStructure` .. code:: python @@ -554,7 +558,7 @@ General Parameters .. _NeighborListSelectionParameter: .. py:class:: NeighborListSelectionParameter - This parameter represents a :ref:`DataPath` object that has an end point of a 'cx.NeighborList' object + This parameter represents a :ref:`DataPath ` object that has an end point of a 'cx.NeighborList' object .. _NumericTypeParameter: .. py:class:: NumericTypeParameter diff --git a/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst b/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst index ce80974dc3..640c6e4589 100644 --- a/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst +++ b/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst @@ -3,6 +3,7 @@ Writing a New Python Filter 1. Generating the Skeleton Code ----------------------------------------------------------------- + **Generate Python Plugin and/or Python Filters** is a powerful filter in *simplnx* that kickstarts the development of new Python filters by generating the skeleton code for the new filters. This filter can generate skeleton code for the new filters in an existing Python plugin, or it can also generate the skeleton code for a new Python plugin. @@ -15,6 +16,7 @@ This filter can generate skeleton code for the new filters in an existing Python #. **Configure the Filter:** **New Python Plugin** .. image:: Images/Generate_Python_Plugin.png + - Turn OFF *Use Existing Plugin*. - Input the programmatic name and human name for the new plugin. - Select the output directory for the new plugin. @@ -22,6 +24,7 @@ This filter can generate skeleton code for the new filters in an existing Python **Existing Python Plugin** .. image:: Images/Generate_Python_Plugin_2.png + - Turn ON *Use Existing Plugin*. - Select the existing plugin location on the file system (the top-level directory of the existing plugin). - Set the desired programmatic names for your new filters (separated by commas). @@ -32,7 +35,8 @@ This filter can generate skeleton code for the new filters in an existing Python - If *Use Existing Plugin* is ON, then the new filters will be generated inside the existing plugin. 2. Understanding the Filter Skeleton Structure ---------------------------------------- +---------------------------------------------- + The skeleton provides a basic structure with placeholders and conventions that align with *simplnx*'s architecture. **Components:** diff --git a/wrapping/python/docs/source/conf.py b/wrapping/python/docs/source/conf.py index ac7eabc7d7..34f7dcee76 100644 --- a/wrapping/python/docs/source/conf.py +++ b/wrapping/python/docs/source/conf.py @@ -23,7 +23,7 @@ templates_path = ['_templates'] exclude_patterns = [] - +suppress_warnings = ['autosectionlabel.*'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output