D338: Doc/overall review_part2 (#341) (#346)

* Overall doc review--edit of base RST files * Fix codespell herror * Apply suggestions from code review * Fix link target * add missing link targets * Fix file name in overall index.rst file * Fix link to Contribute topic in README * Submit RST file edits based on HTML rendering * Edit PY files in core/definition * Edits to definition PY files based on doc rendering Edits to geometry PY files * Fix code style issues * Edits to hierarchy PY files * Edits in inner PY files * Edits to PY files * Fix formatting issues from late Friday * Push first-round edits to PY files not yet reviwewd * Update src/ansys/edb/core/geometry/point3d_data.py * Fix code style issue * Format properties and defaults consistently * Fix tagging mistake * Fix another tag * Fix bad role tagging * Clean up of PY files through middle of geometry directory * Changes through geometry folder * Additoinal edits based on visual rendering of additional PY files * Edit RN RST file * Fix one more tag issue --------- Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: SMoraisAnsys <[email protected]>
ansys · Jan 2, 2024 · f76d479 · f76d479
1 parent 52af9c1
commit f76d479
Show file tree

Hide file tree

Showing 98 changed files with 2,597 additions and 2,914 deletions.
diff --git a/README.rst b/README.rst
@@ -25,7 +25,7 @@ The documentation has five sections:
 - `API reference <https://edb.core.docs.pyansys.com/version/dev/api/index.html>`_: Provides API member descriptions
   and usage examples.
 - `Examples <https://edb.core.docs.pyansys.com/version/dev/examples/index.html>`_: Provides examples showing
-- end-to-end workflows for using PyEDB-Core.
+  end-to-end workflows for using PyEDB-Core.
 - `Contribute <https://edb.core.docs.pyansys.com/version/dev/contribute.html>`_: Describes how to install
   PyEDB-Core in developer mode and how to contribute to this PyAnsys library.
 

diff --git a/doc/source/api/hierarchy.rst b/doc/source/api/hierarchy.rst
@@ -1,8 +1,8 @@
 Hierarchy
 =========
 
-Hierarchy objects are :term:`Connectables <Connectable>` that can act as a container for other :term:`Connectables <Connectable>`.
-Sub-designs, MCAD Components, Coordinate systems etc.. are all examples of hierarchy objects.
+Hierarchy objects are :term:`connectables <Connectable>` that can act as a container for other :term:`connectables <Connectable>`.
+Examples of hierarchy objects include subdesigns, MCAD components, and coordinate systems.
 
 
 Object types

diff --git a/doc/source/api/release_notes.rst b/doc/source/api/release_notes.rst
@@ -4,7 +4,7 @@ Release notes
 v1.0
 ----
 
-Known issues:
+**Known issues**
 
 * If a new database is opened after another one is closed, the server may fail to properly fetch objects that are created after the new database is opened.
   See `issue #154 <https://github.com/ansys/pyedb-core/issues/154>`_.
diff --git a/src/ansys/edb/core/database.py b/src/ansys/edb/core/database.py
@@ -37,7 +37,7 @@ class ProductIdType(Enum):
     """Provides an enum representing IDs of Ansys products that support EDB usage.
 
     - HFSS_3D_LAYOUT
-    - DESIGNER (Deprecated. Use HFSS_3D_LAYOUT instead.)
+    - DESIGNER (Deprecated. Use ``HFSS_3D_LAYOUT`` instead.)
     - SIWAVE
     - GENERIC_TRANSLATOR
     - USER_DEFINED
@@ -67,12 +67,12 @@ def __init__(self, msg):
 
     @classmethod
     def create(cls, db_path):
-        """Create a database at the specified file location.
+        """Create a database in a given location.
 
         Parameters
         ----------
         db_path : str
-            Path to the top-level database folder.
+            Path to the top-level database directory.
 
         Returns
         -------
@@ -83,19 +83,19 @@ def create(cls, db_path):
 
     @classmethod
     def open(cls, db_path, read_only):
-        """Open an existing database at the specified file location.
+        """Open a database in a given location.
 
         Parameters
         ----------
         db_path : str
-            Path to the top-level database folder.
+            Path to the top-level database directory.
         read_only : bool
             Whether to open the database in read-only mode.
 
         Returns
         -------
         Database object or None
-            Opened database object or ``None`` if no database object is found.
+            Database object opened or ``None`` if no database object is found.
         """
         return Database(
             cls.__stub.Open(
@@ -108,17 +108,17 @@ def open(cls, db_path, read_only):
 
     @classmethod
     def delete(cls, db_path):
-        """Delete a database at the specified file location.
+        """Delete a database in a given specified location.
 
         Parameters
         ----------
         db_path : str
-            Path to the top-level database folder.
+            Path to the top-level database directory.
         """
         cls.__stub.Delete(proto_wrappers.StringValue(value=db_path))
 
     def save(self):
-        """Save any changes to a file."""
+        """Save any changes to the database."""
         self.__stub.Save(self.msg)
 
     def close(self):
@@ -137,54 +137,27 @@ def _map_cell_edb_obj_collection(cells_msg):
 
     @property
     def top_circuit_cells(self):
-        """Top circuit cells in the database.
-
-        Returns
-        -------
-        list[:class:`Cell <ansys.edb.core.layout.Cell>`]
-        """
+        """:obj:`list` of :class:`Cell <ansys.edb.core.layout.Cell>`: Top circuit cells in the database."""
         return Database._map_cell_edb_obj_collection(self.__stub.GetTopCircuits(self.msg))
 
     @property
     def circuit_cells(self):
-        """All circuit cells in the database.
-
-        Returns
-        -------
-        list[:class:`Cell <ansys.edb.core.layout.Cell>`]
-        """
+        """:obj:`list` of :class:`Cell <ansys.edb.core.layout.Cell>`: All circuit cells in the database."""
         return Database._map_cell_edb_obj_collection(self.__stub.GetCircuits(self.msg))
 
     @property
     def footprint_cells(self):
-        """All footprint cells in the database.
-
-        Returns
-        -------
-        list[:class:`Cell <ansys.edb.core.layout.Cell>`]
-        """
+        """:obj:`list` of :class:`Cell <ansys.edb.core.layout.Cell>`: All footprint cells in the database."""
         return Database._map_cell_edb_obj_collection(self.__stub.GetFootprints(self.msg))
 
     @property
     def edb_uid(self):
-        """Unique EDB ID of the database.
-
-        Returns
-        -------
-        int
-            Unique EDB ID of the database.
-        """
+        """:obj:`int`: Unique EDB ID of the database."""
         return self.__stub.GetId(self.msg).value
 
     @property
     def is_read_only(self):
-        """Flag indicating if the database is open in read-only mode.
-
-        Returns
-        -------
-        bool
-            ``True`` when the database is open in read-only mode, ``False`` otherwise.
-        """
+        """:obj:`bool`: Flag indicating if the database is open in read-only mode."""
         return self.__stub.IsReadOnly(self.msg).value
 
     @classmethod
@@ -210,8 +183,8 @@ def save_as(self, path, version=""):
         ----------
         path : str
             Location for saving the new database file to.
-        version : str, optional
-            EDB version for the new database file. The default is ``""``, which means that
+        version : str, default: ""
+            EDB version for the new database file. The default is ``""``, in which case
             the new database file is saved for the current version.
         """
         self.__stub.SaveAs(
@@ -220,7 +193,7 @@ def save_as(self, path, version=""):
 
     @classmethod
     def get_version_by_release(cls, release):
-        """Get the EDB version corresponding to a given release name.
+        """Get the EDB version for a given release name.
 
         Parameters
         ----------
@@ -236,17 +209,11 @@ def get_version_by_release(cls, release):
 
     @property
     def directory(self):
-        """Directory of the database.
-
-        Returns
-        -------
-        str
-            Directory of the Database.
-        """
+        """:obj:`str`: Directory where the database is located."""
         return self.__stub.GetDirectory(self.msg).value
 
     def get_product_property(self, prod_id, attr_it):
-        """Get the product-specific property value.
+        """Get a product-specific property value.
 
         Parameters
         ----------
@@ -265,7 +232,7 @@ def get_product_property(self, prod_id, attr_it):
         ).value
 
     def set_product_property(self, prod_id, attr_it, prop_value):
-        """Set the product property associated with the given product and attribute IDs.
+        """Set the product property associated with the given product ID and attribute ID.
 
         Parameters
         ----------
@@ -281,7 +248,7 @@ def set_product_property(self, prod_id, attr_it, prop_value):
         )
 
     def get_product_property_ids(self, prod_id):
-        """Get a list of attribute IDs corresponding to a product property ID.
+        """Get a list of attribute IDs for a given product property ID.
 
         Parameters
         ----------
@@ -307,9 +274,9 @@ def import_material_from_control_file(self, control_file, schema_dir=None, appen
             Full path to the control file.
         schema_dir : str
             Path to the schema directory.
-        append : bool, optional
-            Whether to keep existing materials in the database. The default is ``True``. If
-            ``False``, the existing materials in the database are removed.
+        append : bool, default: True
+            Whether to keep existing materials in the database. If ``False``, the
+            existing materials in the database are removed.
         """
         self.__stub.ImportMaterialFromControlFile(
             database_pb2.ImportMaterialFromControlFileMessage(
@@ -322,13 +289,7 @@ def import_material_from_control_file(self, control_file, schema_dir=None, appen
 
     @property
     def version(self):
-        """Version of the database.
-
-        Returns
-        -------
-        tuple(int, int)
-            Tuple of the version numbers [major, minor].
-        """
+        """:obj:`tuple` of (:obj:`int`, :obj:`int`): Version [major, minor] of the database."""
         version_msg = self.__stub.GetVersion(self.msg)
         return version_msg.major.id, version_msg.minor.id
 
@@ -344,15 +305,7 @@ def scale(self, scale_factor):
 
     @property
     def source(self):
-        """Source name for this database.
-
-        This attribute is also used to set the source name.
-
-        Returns
-        -------
-        str
-            Name of the source
-        """
+        """:obj:`str`: Name of the source database."""
         return self.__stub.GetSource(self.msg).value
 
     @source.setter
@@ -361,24 +314,15 @@ def source(self, source):
 
     @property
     def source_version(self):
-        """Source version for this database.
-
-        This attribute is also used to set the version.
-
-        Returns
-        -------
-        str
-            version string
-
-        """
+        """:obj:`str`: Source version for the database."""
         return self.__stub.GetSourceVersion(self.msg).value
 
     @source_version.setter
     def source_version(self, source_version):
         self.__stub.SetSourceVersion(edb_obj_name_message(self, source_version))
 
     def copy_cells(self, cells_to_copy):
-        """Copy Cells from other databases or this database into this database.
+        """Copy cells from other databases or this database into this database.
 
         Parameters
         ----------
@@ -417,84 +361,52 @@ def _get_bondwire_definition_objs(self, def_class, bw_def_type_enum):
 
     @property
     def apd_bondwire_defs(self):
-        """All APD bondwire definitions in the database.
-
-        Returns
-        -------
-        list[:class:`ApdBondwireDef <ansys.edb.core.definition.ApdBondwireDef>`]
-        """
+        """:obj:`list` of :class:`ApdBondwireDef <ansys.edb.core.definition.ApdBondwireDef>`: All APD \
+        bondwire definitions in the database."""
         return self._get_bondwire_definition_objs(ApdBondwireDef, BondwireDefType.APD_BONDWIRE_DEF)
 
     @property
     def jedec4_bondwire_defs(self):
-        """All JEDEC4 bondwire definitions in the database.
-
-        Returns
-        -------
-        list[:class:`Jedec4BondwireDef <ansys.edb.core.definition.Jedec4BondwireDef>`]
-        """
+        """:obj:`list` of :class:`Jedec4BondwireDef <ansys.edb.core.definition.Jedec4BondwireDef>`: All JEDEC4 \
+        bondwire definitions in the database."""
         return self._get_bondwire_definition_objs(
             Jedec4BondwireDef, BondwireDefType.JEDEC4_BONDWIRE_DEF
         )
 
     @property
     def jedec5_bondwire_defs(self):
-        """All JEDEC5 bondwire definitions in the database.
-
-        Returns
-        -------
-        list[:class:`Jedec5BondwireDef <ansys.edb.core.definition.Jedec5BondwireDef>`]
-        """
+        """:obj:`list` of:class:`Jedec5BondwireDef <ansys.edb.core.definition.Jedec5BondwireDef>`: All JEDEC5 \
+        bondwire definitions in the database."""
         return self._get_bondwire_definition_objs(
             Jedec5BondwireDef, BondwireDefType.JEDEC5_BONDWIRE_DEF
         )
 
     @property
     def padstack_defs(self):
-        """All padstack definitions in the database.
-
-        Returns
-        -------
-        list[:class:`PadstackDef <ansys.edb.core.definition.PadstackDef>`]
-        """
+        """:obj:`list` of :class:`PadstackDef <ansys.edb.core.definition.PadstackDef>`: All padstack definitions \
+        in the database."""
         return self._get_definition_objs(PadstackDef, DefinitionObjType.PADSTACK_DEF)
 
     @property
     def package_defs(self):
-        """All package definitions in the database.
-
-        Returns
-        -------
-        list[:class:`PackageDef <ansys.edb.core.definition.PackageDef>`]
-        """
+        """:obj:`list` of :class:`PackageDef <ansys.edb.core.definition.PackageDef>`: All package definitions \
+        in the database."""
         return self._get_definition_objs(PackageDef, DefinitionObjType.PACKAGE_DEF)
 
     @property
     def component_defs(self):
-        """All component definitions in the database.
-
-        Returns
-        -------
-        list[:class:`ComponentDef <ansys.edb.core.definition.ComponentDef>`]
-        """
+        """:obj:`list` of :class:`ComponentDef <ansys.edb.core.definition.ComponentDef>`: All component \
+        definitions in the database."""
         return self._get_definition_objs(ComponentDef, DefinitionObjType.COMPONENT_DEF)
 
     @property
     def material_defs(self):
-        """All material definitions in the database.
-
-        Returns
-        -------
-        list[:class:`MaterialDef <ansys.edb.core.definition.MaterialDef>`]
-        """
+        """:obj:`list` of :class:`MaterialDef <ansys.edb.core.definition.MaterialDef>`: All material \
+        definitions in the database."""
         return self._get_definition_objs(MaterialDef, DefinitionObjType.MATERIAL_DEF)
 
     @property
     def dataset_defs(self):
-        """All dataset definitions in the database.
-
-        Returns
-        -------
-        list[:class:`DatasetDef <ansys.edb.core.definition.DatasetDef>`]
-        """
+        """:obj:`list` of :class:`DatasetDef <ansys.edb.core.definition.DatasetDef>`: All dataset \
+        definitions in the database."""
         return self._get_definition_objs(DatasetDef, DefinitionObjType.DATASET_DEF)