Provide editorial review (#249)

* Provide editorial review, preparing for implementation of Vale, a prose linter * Fix typo * Fix formatting * Fix process chemical footnote ref * Misc docs fixes * Apply suggestions from code review Accept all of Andy's revisions. Co-authored-by: Andy Grigg <andrew.grigg@ansys.com> * Parametetrs -> Attributes Co-authored-by: Andy Grigg <andrew.grigg@ansys.com>
ansys · Dec 15, 2022 · 10cc2ad · 10cc2ad
1 parent 6fda193
commit 10cc2ad
Show file tree

Hide file tree

Showing 42 changed files with 799 additions and 635 deletions.
diff --git a/README.rst b/README.rst
@@ -3,24 +3,24 @@ ansys-grantami-bomanalytics
 
 Project Overview
 ----------------
-This project is part of the larger PyAnsys effort to facilitate the use
-of Ansys technologies directly from within Python.
+Granta MI BoM Analytics is part of the larger `PyAnsys <https://github.com/pyansys>`_
+effort to facilitate the use of Ansys technologies directly from Python.
 
 The Granta MI Restricted Substances solution includes a REST API for
-evaluating compliance of products, assemblies, specifications and
+evaluating compliance of products, assemblies, specifications, and
 materials against legislations. This package abstracts automatically-
 generated code into an easy-to-use client library.
 
 
 Installation
 ------------
-Install ansys-grantami-bomanalytics with:
+Install the ``ansys-grantami-bomanalytics`` package with this code:
 
 .. code::
 
    pip install ansys-grantami-bomanalytics
 
-Alternatively, clone and install with:
+Alternatively, clone and install thie package with this code:
 
 .. code::
 
@@ -31,13 +31,13 @@ Alternatively, clone and install with:
 
 Documentation
 -------------
-See `Granta MI BoM Analytics Documentation <https://grantami.docs.pyansys.com>`_
-for more details.
+The `Granta MI BoM Analytics Documentation <https://grantami.docs.pyansys.com>`_
+provides comprehensive installation and usage information.
 
 
 Usage
 -----
-Here's a brief example of how the package works:
+Here's a brief example of how to use Granta MI BoM Analytics:
 
 .. code:: python
 
@@ -64,11 +64,10 @@ Here's a brief example of how the package works:
 
 Testing
 -------
-See `Contributing <https://grantami.docs.pyansys.com/contributing>`_
-for more details.
+For information on testing, see `Contributing <https://grantami.docs.pyansys.com/contributing>`_.
 
 
 License
 -------
-The library is provided under the terms of the MIT license, you can find
-the license text in the LICENSE file at the root of the repository.
+Granta MI BoM Analytics is provided under the terms of the MIT license. You can find
+this license in the LICENSE file at the root of the repository.
diff --git a/doc/source/api/batching.rst b/doc/source/api/batching.rst
@@ -1,10 +1,8 @@
 .. _ref_grantami_bomanalytics_batching:
 
-Batching Requests
+Batching requests
 =================
 
-Introduction
-------------
 Queries performed with this package are batched if they exceed a certain size. When
 you perform a query, batching is achieved by splitting the list of parts and materials
 into smaller lists to reduce the overall time it takes to obtain results.
@@ -13,22 +11,22 @@ The exact optimal size for batching cannot be determined generally because it de
 on the data that is used to determine impacted substances and compliance. Given the
 following conditions, you might need to change the batch size.
 
-Very Complex Part and Specification Hierarchies
+Very complex part and specification hierarchies
 -----------------------------------------------
 Parts and specifications in Granta MI can be defined recursively. For example, it's possible
 to define parts and specifications in terms of other parts and specifications. To take this
 into consideration, the default batch size for parts and specifications is very small. However,
 for a very complex hierarchy, you might need to further decrease the batch size.
 
-Very Simple Part and Specification Hierarchies
+Very simple part and specification hierarchies
 ----------------------------------------------
 Part and specification structures are very simple if they have a similar complexity to materials.
 For example, a very simple hierarchy might directly reference substances or reference a small number
 of materials. For a very simple hierarchy, you might need to increase the batch size.
 
-Large Numbers of Indicators or Legislations
+Large numbers of indicators or legislations
 -------------------------------------------
 Queries can only be batched in the ``item`` dimension. There is no facility to split the query
 by the number of legislations or indicators. As a result, if queries for impacted substances or
-compliance are evaluated against a large number of legislations or lists (typically > 10), you
-might need to decrease the batch size.
+compliance are evaluated against a large number of legislations or lists (typically greater than
+10), you might need to decrease the batch size.
diff --git a/doc/source/api/common.rst b/doc/source/api/common.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_common_connection:
 
-Granta MI Connection
+Granta MI connection
 ====================
 
-Connection Builder
+Connection builder
 ~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.Connection
@@ -15,15 +15,15 @@ Connection Builder
    .. automethod:: with_anonymous
 
 
-BoM Analytics Client
+BoM Analytics client
 ~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._connection.BomAnalyticsClient
    :members:
 
 .. _ref_grantami_bomanalytics_common_messages:
 
-Log Messages
+Log messages
 ============
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.LogMessage

diff --git a/doc/source/api/compliance/bom.rst b/doc/source/api/compliance/bom.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_compliance_bom:
 
-BoM Compliance
+BoM compliance
 ==============
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.BomComplianceQuery
@@ -12,7 +12,7 @@ Query Definition
    .. automethod:: with_indicators
    .. automethod:: with_bom
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.BomComplianceQueryResult

diff --git a/doc/source/api/compliance/index.rst b/doc/source/api/compliance/index.rst
@@ -3,7 +3,7 @@
 Compliance API
 ==============
 
-This section provides an overview of the Compliance API. The
+This section provides an overview of the API for compliance. The
 :ref:`ref_grantami_bomanalytics_api_compliance_substances`,
 :ref:`ref_grantami_bomanalytics_api_compliance_materials`,
 :ref:`ref_grantami_bomanalytics_api_compliance_specifications`, and
@@ -14,7 +14,7 @@ a threshold. If a certain record directly or indirectly contains substances impa
 legislations in an amount that exceeds the threshold, the record is not compliant with that indicator. For more
 information about possible results, see the definitions of the indicators.
 
-The :ref:`ref_grantami_bomanalytics_api_compliance_bom` query accepts a Bill of Materials in Ansys Granta MI 1711 XML BoM format and
+The :ref:`ref_grantami_bomanalytics_api_compliance_bom` query accepts a BoM (bill of materials) in Ansys Granta MI 1711 XML BoM format and
 returns the compliance status of the BoM based on the Granta MI records referenced by it.
 
 In general, the result of each query is a recursive BoM (or multi-level BoM) that shows the compliance status and impacted

diff --git a/doc/source/api/compliance/indicators.rst b/doc/source/api/compliance/indicators.rst
@@ -2,28 +2,28 @@
 
 Indicators
 ==========
-The BoM Analytics API determines compliance against an indicator, which essentially represents a legislation
+The Granta MI BoM Analytics API determines compliance against an indicator, which essentially represents a legislation
 with a threshold. If a substance appears in a certain item, either directly or indirectly, in a quantity that exceeds that
 threshold, the item is non-compliant with that indicator. In cases where the
-legislation defines a per-substance threshold (for example, RoHS), then this per-substance threshold will be used instead.
+legislation defines a per-substance threshold (for example, RoHS), then this per-substance threshold is used instead.
 
-Indicators can include a list of legislations, in which case a substance will be impacted by the indicator if it is
+Indicators can include a list of legislations, in which case a substance is impacted by the indicator if it is
 impacted by one or more legislations included in that indicator.
 
 There are two different types of indicator, and they compute compliance in slightly different ways. It is therefore
 important to understand the differences between them. For more information, see the *Granta MI Restricted Substances
 Reports User Guide* supplied with Granta MI Restricted Substances Reports.
 
 
-RoHS Indicator
+RoHS indicator
 --------------
 
 .. autoclass:: ansys.grantami.bomanalytics.indicators.RoHSIndicator
 
 .. autoenum:: ansys.grantami.bomanalytics.indicators.RoHSFlag
 
 
-Watch List Indicator
+Watch list indicator
 --------------------
 
 .. autoclass:: ansys.grantami.bomanalytics.indicators.WatchListIndicator

diff --git a/doc/source/api/compliance/materials.rst b/doc/source/api/compliance/materials.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_compliance_materials:
 
-Material Compliance
+Material compliance
 ===================
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.MaterialComplianceQuery
@@ -17,7 +17,7 @@ Query Definition
    .. automethod:: with_stk_records
    .. automethod:: with_batch_size
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.MaterialComplianceQueryResult
@@ -28,7 +28,7 @@ Query Result
    .. autoattribute:: compliance_by_material_and_indicator
    .. autoattribute:: messages
 
-Material Result
+Material result
 ~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._item_results.MaterialWithComplianceResult
diff --git a/doc/source/api/compliance/parts.rst b/doc/source/api/compliance/parts.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_compliance_parts:
 
-Part Compliance
+Part compliance
 ===============
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.PartComplianceQuery
@@ -18,7 +18,7 @@ Query Definition
    .. automethod:: with_batch_size
 
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.PartComplianceQueryResult
@@ -30,7 +30,7 @@ Query Result
    .. autoattribute:: messages
 
 
-Part Result
+Part result
 ~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._item_results.PartWithComplianceResult
diff --git a/doc/source/api/compliance/specifications.rst b/doc/source/api/compliance/specifications.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_compliance_specifications:
 
-Specification Compliance
+Specification compliance
 ========================
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.SpecificationComplianceQuery
@@ -18,7 +18,7 @@ Query Definition
    .. automethod:: with_batch_size
 
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.SpecificationComplianceQueryResult
@@ -30,13 +30,13 @@ Query Result
    .. autoattribute:: messages
 
 
-Specification Result
+Specification result
 ~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._item_results.SpecificationWithComplianceResult
 
 
-Coating Result
+Coating result
 ~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._item_results.CoatingWithComplianceResult
diff --git a/doc/source/api/compliance/substances.rst b/doc/source/api/compliance/substances.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_compliance_substances:
 
-Substance Compliance
+Substance compliance
 ====================
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.SubstanceComplianceQuery
@@ -25,7 +25,7 @@ Query Definition
    .. automethod:: with_stk_records
    .. automethod:: with_batch_size
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.SubstanceComplianceQueryResult
@@ -36,7 +36,7 @@ Query Result
    .. autoattribute:: compliance_by_substance_and_indicator
    .. autoattribute:: messages
 
-Substance Result
+Substance result
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._item_results.SubstanceWithComplianceResult
diff --git a/doc/source/api/impacted_substances/bom.rst b/doc/source/api/impacted_substances/bom.rst
@@ -1,11 +1,11 @@
 .. _ref_grantami_bomanalytics_api_impactedsubstances_bom:
 
-BoM Impacted Substances Query
-=============================
+BoM impacted substances
+=======================
 
 .. _ref_grantami_bomanalytics_api_impactedsubstances_bom_query:
 
-Query Definition
+Query definition
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics.queries.BomImpactedSubstancesQuery
@@ -16,7 +16,7 @@ Query Definition
 
 .. _ref_grantami_bomanalytics_api_impactedsubstances_bom_queryresult:
 
-Query Result
+Query result
 ~~~~~~~~~~~~
 
 .. autoclass:: ansys.grantami.bomanalytics._query_results.BomImpactedSubstancesQueryResult
@@ -26,14 +26,14 @@ Query Result
    .. autoattribute:: impacted_substances
    .. autoattribute:: messages
 
-BoM Result
+BoM result
 ~~~~~~~~~~
 
 The ``BoMWithImpactedSubstancesResult`` object does exist, but it is not documented because it is not exposed by any
 public methods. The rationale is as follows:
 
-A single :ref:`ref_grantami_bomanalytics_api_impactedsubstances_bom_query` query can only operate on a single BoM.
+A single :ref:`ref_grantami_bomanalytics_api_impactedsubstances_bom_query` can only operate on a single BoM.
 Therefore, there is no grouping of impacted substances by BoM, which is what the ``BoMWithImpactedSubstancesResult``
-would be used for. :ref:`ref_grantami_bomanalytics_api_impactedsubstances_substances` objects are only available either
+object would be used for. :ref:`ref_grantami_bomanalytics_api_impactedsubstances_substances` objects are only available either
 as a flat list or grouped by legislation. Both of these views are available on the
-:ref:`ref_grantami_bomanalytics_api_impactedsubstances_bom_queryresult` object above.
+:ref:`ref_grantami_bomanalytics_api_impactedsubstances_bom_queryresult` object.
diff --git a/doc/source/api/impacted_substances/impacted_substances.rst b/doc/source/api/impacted_substances/impacted_substances.rst
@@ -1,6 +1,6 @@
 .. _ref_grantami_bomanalytics_api_impactedsubstances_substances:
 
-Impacted Substances
+Impacted substances
 ===================
 
 

diff --git a/doc/source/api/impacted_substances/index.rst b/doc/source/api/impacted_substances/index.rst
@@ -1,9 +1,9 @@
 .. _ref_grantami_bomanalytics_api_impactedsubstances_index:
 
-Impacted Substances API
+Impacted substances API
 =======================
 
-This section gives an overview of the Impacted Substances API. The
+This section gives an overview of the API for impacted substances. The
 :ref:`ref_grantami_bomanalytics_api_impactedsubstances_materials`,
 :ref:`ref_grantami_bomanalytics_api_impactedsubstances_specifications`, and
 :ref:`ref_grantami_bomanalytics_api_impactedsubstances_parts` queries accept a list of references to records in a