Overall doc review

AUTHORS

@@ -5,7 +5,7 @@
 # For contributions made under a Corporate CLA, the organization is
 # added to this file.
 #
-# If you have contributed to the repository and wish to be added to this file
+# If you have contributed to the repository and want to be added to this file
 # please submit a request.
 #
 #

README.md

@@ -11,62 +11,65 @@
 [![PythonVersion](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
 [![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)[!
 
-## What is PyEDB ?
+## What is PyEDB?
 
-ANSYS EDB is very powerful for processing complex and large layout design. EDB-core native API
-can be used to automate workflows. However, it requires a deep comprehension of the architecture and
-classes inheritances, resulting with a learning curve not always compatible with daily work load.
+PyEDB is Python client library for processing complex and large layout designs in the
+Ansys Electronics Database (EDB) format, which stores information describing designs for
+[Ansys Electronics Desktop](https://www.ansys.com/products/electronics)(AEDT).
 
-PyEDB was developed to provide high level classes calling EDB-core API to speed up EDB adoption
-and improve user experience. Thanks to its application oriented architecture PyEDB, users can
-start using EDB faster and easier.
+While you can also use the [PyEDB-Core](https://github.com/ansys/pyedb-core) API to automate EDB workflows,
+using it requires a deep comprehension of the EDB architecture and class inheritances, resulting in
+a learning curve not always compatible with daily work loads.
 
-## Install on CPython from PyPI
-
-You can install PyEDB on CPython 3.7 through 3.10 from PyPI with this command:
-
-```sh
-  pip install pyedb
-```
+To speed up EDB adoption and improve user experience, PyEDB provides high-level classes that call
+the PyEDB-Core API. Thanks to PyEDB's application-oriented architecture, you can start using EDB
+faster and easier.
 
 ## About PyEDB
 
-PyEDB is part of the larger [PyAnsys](https://docs.pyansys.com "PyAnsys") effort to facilitate the use of Ansys technologies directly from Python.
-
-PyEDB is intended to consolidate and extend all existing
-functionalities around scripting for EDB to allow reuse of existing code,
-sharing of best practices, and increased collaboration.
+PyEDB is part of the larger [PyAnsys](https://docs.pyansys.com "PyAnsys") effort to facilitate the use
+of Ansys technologies directly from Python. It is intended to consolidate and extend all existing
+functionalities around scripting for EDB to allow reuse of existing code, sharing of best practices,
+and increased collaboration.
 
-## About EDB
+PyEDB includes functionality for interacting with Ansys electromagnetic simulators: : HFSS,
+HFSS 3D Layout, Icepak, Maxwell, Q3D, and SIwave.
 
-[AEDT](https://www.ansys.com/products/electronics) is a database allowing efficient and fast
-layout design handling and processing for building ready to solve projects. EDB is addressing Signal
-Integrity (SI), Power Integrity (PI-DC) and also Electro-Thermal work flows. The EDB can be
-imported into Electromagnetic Desktop which enables a user to modify layout,
-assign materials, define ports, simulations and constraints and then launch any of
-the various electromagnetic simulators: HFSS, HFSS3Dlayout, SIwave, Icepak, Maxwell, Q3D.
+## What is EDB?
 
-AEDB is running as standalone API and opens aedb folder for directly querying and manipulating
-layout design in memory and does not require opening any User Interface (UI). Hence AEDB is the fastest
-and most efficient way to handle large and complex layout.
+EDB provides a proprietary database file format (AEDB) for efficient and fast layout design
+handling and processing for building ready-to-solve projects. EDB addresses signal integrity
+(SI), power integrity (PI-DC), and electro-thermal work flows. You can import an AEDB file
+into AEDT to modify the layout, assign materials, and define ports, simulations, and constraints.
+You can then launch any of the Ansys electromagnetic simulators.
 
-AEDB can also been parsed with and Electromagnetic simulator command line like HFSS or SIwave in bacth.
-Therefore, completely non graphically flows can be deployed from layout translation up to simulatiom results.
-AEDB can also be imported in ANSYS AEDT with PyAEDT for example to display the project, combining 3D design or performing simulation post-processing. AEDB also supports 3D component models.
+EDB runs as a standalone API, which means that you don't need to open a user interface (UI).
+Because EDB opens the ``aedb`` folder for directly querying and manipulating layout design in
+memory, it provides the fastest and most efficient way to handle a large and complex layout.
 
-`PyEDB` is licensed under the [MIT License](https://github.com/ansys/pyedb/blob/main/LICENSE)
+You can also parse an AEDB file from a command line in batch in an Ansys electromagnetic simulator
+like HFSS or SIwave. Thus, you can deploy completely non-graphical flows, from layout
+translation through simulatiom results.
 
-PyEDB includes functionality for interacting with the following AEDT tools and Ansys products:
-
-  - HFSS 3D Layout
-  - Icepak
-  - EDB
-  - Icepak
+Additionally, you can use PyAEDT to import an AEDB file into AEDT to view a project,
+combine 3D designs, or perform simulation postprocessing. EDB also supports 3D component models.
 
 ## Documentation and issues
 
 Documentation for the latest stable release of PyEDB is hosted at
 [PyEDB documentation](https://edb.docs.pyansys.com/version/dev/index.html).
+The documentation has five sections:
+
+- `Getting started <https://edb.docs.pyansys.com/version/version/dev/getting_started/index.html#>`_: Describes
+  how to install PyEDB in user mode.
+- `User guide <https:edb.docs.pyansys.com/version/version/dev/user_guide/index.html>`_: Describes how to
+  use PyEDB.
+- `API reference <edb.docs.pyansys.com/version/version/dev/api/index.html>`_: Provides API member descriptions
+  and usage examples.
+- `Examples <https://edb.docs.pyansys.com/version/version/dev/examples/index.html>`_: Provides examples showing
+  end-to-end workflows for using PyEDB.
+- `Contribute <https://edb.docs.pyansys.com/version/version/dev/contribute.html>`_: Describes how to install
+  PyEDB in developer mode and how to contribute to this PyAnsys library.
 
 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
@@ -81,38 +84,12 @@ you can post questions, share ideas, and get community feedback.
 
 To reach the project support team, email [[email protected]](mailto:[email protected]).
 
-## Dependencies
-
-To run PyEDB, you must have a local licenced copy of AEDT.
-PyEDB supports AEDT versions 2022 R1 or newer.
-
-## Why PyEDB ?
-
-ANSYS EDB is very powerful for processing complex and large layout design. EDB-core native API
-can be used to automate workflows. However it requires a deep comprehension of the architecture and
-classes inheritances, resulting with a learning curve not always compatible with daily work load.
-
-PyEDB was developed to provide high level classes calling EDB-core API to speed up EDB adoption
-and improve user experience. Thanks to its application oriented architecture PyEDB, users can
-start using EDB faster and easier.
-
-## Example
-
-``` python
-from pyedb.dotnet.edb import Edb
-from pyedb.generic.general_methods import generate_unique_folder_name
-import pyedb.misc.downloads as downloads
-
-temp_folder = generate_unique_folder_name()
-targetfile = downloads.download_file("edb/ANSYS-HSD_V1.aedb", destination=temp_folder)
-edbapp = Edb(edbpath=targetfile, edbversion="2023.2")
-```
 ## License
 
-PyEDB is licensed under the MIT license.
+PyEDB is licensed under the [MIT License](https://github.com/ansys/pyedb/blob/main/LICENSE).
 
 PyEDB makes no commercial claim over Ansys whatsoever. This library extends the
-functionality of EDB by adding a Python interface to EDB-core without changing the
+functionality of EDB by adding a Python interface to PyEDB-Core without changing the
 core behavior or license of the original software. The use of PyEDB requires a
 legally licensed local copy of AEDT.
 

doc/source/_static/custom.css

@@ -28,18 +28,14 @@
   color: #150458 !important;
   font-size: var(--pst-font-size-h5);
   font-weight: bold;
-  padding: .5rem 0rem 0.5rem 0rem;
-  text-align: center;
+  padding: .1rem 0rem 0.5rem 0rem;
 }
 
 .sd-card .sd-card-footer .sd-card-text {
   max-width: 220px;
   margin-left: auto;
   margin-right: auto;
 }
-.sd-card  .sd-card-text {
-  text-align: center;
-}
 
 nav.bd-links ul li.toctree-l1 > a {
   font-size: .90rem;

doc/source/api/index.rst

@@ -1,24 +1,25 @@
-=======
-EDB API
-=======
+=============
+API reference
+=============
 
-This section describes EDB classes, methods, and functions
+This section describes EDB functions, classes, and methods
 for EDB apps and modules. Use the search feature or click links
 to view API documentation.
 
-The PyEDB EDB API includes classes for apps and modules. You must initialize the
-EDB class to get access to all modules and methods.
-All other classes and methods are inherited into the app class.
+The PyEDB API includes classes for apps and modules. You must initialize the
+``Edb`` class to get access to all modules and methods. All other classes and
+methods are inherited into the ``Edb`` class.
+
 If EDB is launched within the ``HfssdLayout`` class, EDB is accessible in read-only mode.
 
 
 .. image:: ../resources/edb_intro.png
   :width: 800
-  :alt: EDB Applications
+  :alt: EDB apps
   :target: https://www.ansys.com/applications/pcbs-ics-ic-packages
 
 
-Example:
+**Example**
 
 .. code:: python
 
@@ -42,4 +43,5 @@ Example:
    SimulationEdb
    SimulationConfigurationEdb
    SiWave
-   PortsEdb
+   PortsEdb
+

doc/source/contributing.rst

@@ -0,0 +1,124 @@
+.. _contributing_pyedb:
+
+==========
+Contribute
+==========
+Overall guidance on contributing to a PyAnsys repository appears in
+`Contribute <https://dev.docs.pyansys.com/how-to/contributing.html>`_
+in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar
+with this guide before attempting to contribute to PyEDB.
+
+The following contribution information is specific to PyEDB.
+
+Clone the repository
+--------------------
+To clone and install the latest version of PyEDB in
+development mode, run these commands:
+
+.. code::
+
+    git clone https://github.com/ansys/pyedb
+    cd pyedb
+    python -m pip install --upgrade pip
+    pip install -e .
+
+Post issues
+-----------
+Use the `PyEDB Issues <https://github.com/ansys/pyedb/issues>`_
+page to submit questions, report bugs, and request new features.
+
+To reach the product support team, email `[email protected] <[email protected]>`_.
+
+View PyEDB documentation
+-------------------------
+Documentation for the latest stable release of PyEDB is hosted at
+`PyEDB documentation <https://edb.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
+--------------------
+PyEDB is compliant with `PyAnsys code style
+<https://dev.docs.pyansys.com/coding_style/index.html>`_. It uses the tool
+`pre-commit <https://pre-commit.com/>`_ to check the code style. You can install
+and activate this tool with these commands:
+
+.. code:: bash
+
+  pip install pre-commit
+  pre-commit run --all-files
+
+You can also install this as a pre-commit hook with this command:
+
+.. code:: bash
+
+  pre-commit install
+
+This way, it's not possible for you to push code that fails the style checks.
+For example::
+
+  $ pre-commit install
+  $ git commit -am "Add my cool feature."
+  black....................................................................Passed
+  isort (python)...........................................................Passed
+  flake8...................................................................Passed
+  codespell................................................................Passed
+  fix requirements.txt.....................................................Passed
+  blacken-docs.............................................................Passed
+
+Log errors
+~~~~~~~~~~
+PyEDB has an internal logging tool named ``Messenger``
+and a log file that is automatically generated in the project
+folder.
+
+The following examples show how ``Messenger`` is used to
+write both to the internal AEDT message windows and the log file:
+
+.. code:: python
+
+    self.logger.error("This is an error message.")
+    self.logger.warning("This is a warning message.")
+    self.logger.info("This is an info message.")
+
+These examples show how to write messages only to the log file:
+
+.. code:: python
+
+    self.logger.error("This is an error message.")
+    self.logger.warning("This is a warning message.")
+    self.logger.info("This is an info message.")
+
+
+Handle exceptions
+~~~~~~~~~~~~~~~~~
+PyEDB uses a specific decorator, ``@pyedb_function_handler()``,
+to handle exceptions caused by methods and by the AEDT API.
+This exception handler decorator makes PyEDB fault tolerant
+to errors that can occur in any method.
+
+For example:
+
+.. code:: python
+
+   @pyedb_function_handler()
+   def my_method(self, var):
+       pass
+
+Every method can return a value of ``True`` when successful or
+``False`` when failed. When a failure occurs, the error
+handler returns information about the error in both the console and
+log file.
+
+Hard-coded values
+~~~~~~~~~~~~~~~~~~
+Do not write hard-coded values to the registry. Instead, use the Configuration service.
+
+Maximum line length
+~~~~~~~~~~~~~~~~~~~
+Best practice is to keep the length at or below 120 characters for code
+and comments. Lines longer than this might not display properly on some terminals
+and tools or might be difficult to follow.