FEAT: Further documentation (#19)

* FEAT: Add top level port interconnection

* FEAT: Integrating further functionality

* FEAT: Sorted out docs build

.github/workflows/code_coverage.yaml

@@ -0,0 +1,4 @@
+- name: Upload coverage reports to Codecov
+  uses: codecov/codecov-action@v3
+  env:
+    CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

README.rst

@@ -1,7 +1,7 @@
 **P**\hotonic **I**\ntegrated **EL**\ectronics
 ===============================================
 
-|PyPI Version| |Build Status| |Documentation Status| |Updates|
+|PyPI Name| |PyPI Version| |Build Status| |Documentation Status| |MIT| |Black|
 
 Microservices to codesign photonics, electronics, communications,
 quantum, and more.
@@ -37,6 +37,8 @@ microelectronics through the functionality of the
 `IIC-OSIC-TOOLS <https://github.com/iic-jku/iic-osic-tools>`__ and
 photonics via `GDSFactory <https://github.com/gdsfactory/gdsfactory>`__.
 
+.. image:: docs/_static/img/piel_microservice_structure.png
+
 Some existing microservice dependency integrations are:
 
 * `cocotb <https://github.com/cocotb/cocotb>`__ - a coroutine based cosimulation library for writing VHDL and Verilog testbenches in Python.
@@ -53,11 +55,18 @@ Contribution
 If you feel dedicated enough to become a project maintainer, or just
 want to do a single contribution, let's do this together!
 
-.. |PyPI Version| image:: https://img.shields.io/pypi/v/piel.svg
-   :target: https://pypi.python.org/pypi/piel
+
+.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
 .. |Build Status| image:: https://img.shields.io/travis/daquintero/piel.svg
    :target: https://travis-ci.com/daquintero/piel
 .. |Documentation Status| image:: https://readthedocs.org/projects/piel/badge/?version=latest
    :target: https://piel.readthedocs.io/en/latest/?version=latest
+.. |MIT| image:: https://img.shields.io/github/license/gdsfactory/gdsfactory
+   :target: https://choosealicense.com/licenses/mit/
+.. |PyPI Name| image:: https://img.shields.io/badge/pypi-piel-blue
+   :target: https://pypi.python.org/pypi/piel
+.. |PyPI Version| image:: https://img.shields.io/pypi/v/piel.svg
+   :target: https://pypi.python.org/pypi/piel
 .. |Updates| image:: https://pyup.io/repos/github/daquintero/piel/shield.svg
    :target: https://pyup.io/repos/github/daquintero/piel/

docs/autoapi/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+   /autoapi/piel/index
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

docs/autoapi/piel/cli/index.rst

@@ -0,0 +1,27 @@
+:py:mod:`piel.cli`
+==================
+
+.. py:module:: piel.cli
+
+.. autoapi-nested-parse::
+
+   Console script for piel.
+
+
+
+Module Contents
+---------------
+
+
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+   piel.cli.main
+
+
+
+.. py:function:: main(args=None)
+
+   Console script for piel.

docs/autoapi/piel/components/index.rst

@@ -0,0 +1,4 @@
+:py:mod:`piel.components`
+=========================
+
+.. py:module:: piel.components

docs/autoapi/piel/config/index.rst

@@ -0,0 +1,25 @@
+:py:mod:`piel.config`
+=====================
+
+.. py:module:: piel.config
+
+.. autoapi-nested-parse::
+
+   We create a set of parameters that can be used throughout the project for optimisation.
+
+   The numerical solver is normally delegated for as `numpy` but there are cases where a much faster solver is desired, and where different functioanlity is required. For example, `sax` uses `JAX` for its numerical solver. In this case, we will create a global numerical solver that we can use throughout the project, and that can be extended and solved accordingly for the particular project requirements.
+
+
+
+Module Contents
+---------------
+
+.. py:data:: numerical_solver
+
+
+
+.. py:data:: nso
+
+
+
+.. py:data:: piel_path_types

docs/autoapi/piel/defaults/index.rst

@@ -0,0 +1,14 @@
+:py:mod:`piel.defaults`
+=======================
+
+.. py:module:: piel.defaults
+
+
+Module Contents
+---------------
+
+.. py:data:: test_spm_open_lane_configuration
+
+
+
+.. py:data:: example_open_lane_configuration

docs/autoapi/piel/file_conversion/index.rst

@@ -0,0 +1,26 @@
+:py:mod:`piel.file_conversion`
+==============================
+
+.. py:module:: piel.file_conversion
+
+
+Module Contents
+---------------
+
+
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+   piel.file_conversion.read_csv_to_pandas
+   piel.file_conversion.read_vcd_to_json
+
+
+
+.. py:function:: read_csv_to_pandas(file_path: piel.config.piel_path_types)
+
+   This function returns a Pandas dataframe that contains all the simulation data outputted from the simulation run.
+
+
+.. py:function:: read_vcd_to_json(file_path: piel.config.piel_path_types)

docs/autoapi/piel/file_system/index.rst

@@ -0,0 +1,197 @@
+:py:mod:`piel.file_system`
+==========================
+
+.. py:module:: piel.file_system
+
+
+Module Contents
+---------------
+
+
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+   piel.file_system.check_path_exists
+   piel.file_system.check_example_design
+   piel.file_system.copy_source_folder
+   piel.file_system.create_new_directory
+   piel.file_system.delete_path
+   piel.file_system.delete_path_list_in_directory
+   piel.file_system.get_files_recursively_in_directory
+   piel.file_system.permit_script_execution
+   piel.file_system.permit_directory_all
+   piel.file_system.read_json
+   piel.file_system.return_path
+   piel.file_system.run_script
+   piel.file_system.setup_example_design
+   piel.file_system.write_script
+
+
+
+.. py:function:: check_path_exists(path: piel.config.piel_path_types, raise_errors: bool = False) -> bool
+
+   Checks if a directory exists.
+
+   :param path: Input path.
+   :type path: piel_path_types
+
+   :returns: True if directory exists.
+   :rtype: directory_exists(bool)
+
+
+.. py:function:: check_example_design(design_name: str = 'simple_design', designs_directory: piel.config.piel_path_types | None = None) -> bool
+
+   We copy the example simple_design from docs to the `/foss/designs` in the `iic-osic-tools` environment.
+
+   :param design_name: Name of the design to check.
+   :type design_name: str
+   :param designs_directory: Directory that contains the DESIGNS environment flag.
+   :type designs_directory: piel_path_types
+   :param # TODO:
+
+   :returns: None
+
+
+.. py:function:: copy_source_folder(source_directory: piel.config.piel_path_types, target_directory: piel.config.piel_path_types) -> None
+
+   Copies the files from a source_directory to a target_directory
+
+   :param source_directory: Source directory.
+   :type source_directory: piel_path_types
+   :param target_directory: Target directory.
+   :type target_directory: piel_path_types
+
+   :returns: None
+
+
+.. py:function:: create_new_directory(directory_path: str | pathlib.Path) -> None
+
+   Creates a new directory.
+
+   If the parents of the target_directory do not exist, they will be created too.
+
+   :param directory_path: Input path.
+   :type directory_path: str | pathlib.Path
+
+   :returns: None
+
+
+.. py:function:: delete_path(path: str | pathlib.Path) -> None
+
+   Deletes a path.
+
+   :param path: Input path.
+   :type path: str | pathlib.Path
+
+   :returns: None
+
+
+.. py:function:: delete_path_list_in_directory(directory_path: piel.config.piel_path_types, path_list: list, ignore_confirmation: bool = False, validate_individual: bool = False) -> None
+
+   Deletes a list of files in a directory.
+
+   :param directory_path: Input path.
+   :type directory_path: piel_path_types
+   :param path_list: List of files.
+   :type path_list: list
+   :param ignore_confirmation: Ignore confirmation. Default: False.
+   :type ignore_confirmation: bool
+   :param validate_individual: Validate individual files. Default: False.
+   :type validate_individual: bool
+
+   :returns: None
+
+
+.. py:function:: get_files_recursively_in_directory(path: piel.config.piel_path_types, extension: str = '*')
+
+   Returns a list of files in a directory.
+
+   :param path: Input path.
+   :type path: piel_path_types
+   :param extension: File extension.
+   :type extension: str
+
+   :returns: List of files.
+   :rtype: file_list(list)
+
+
+.. py:function:: permit_script_execution(script_path: piel.config.piel_path_types) -> None
+
+   Permits the execution of a script.
+
+   :param script_path: Script path.
+   :type script_path: piel_path_types
+
+   :returns: None
+
+
+.. py:function:: permit_directory_all(directory_path: piel.config.piel_path_types) -> None
+
+   Permits a directory to be read, written and executed. Use with care as it can be a source for security issues.
+
+   :param directory_path: Input path.
+   :type directory_path: piel_path_types
+
+   :returns: None
+
+
+.. py:function:: read_json(path: piel.config.piel_path_types) -> dict
+
+   Reads a JSON file.
+
+   :param path: Input path.
+   :type path: piel_path_types
+
+   :returns: JSON data.
+   :rtype: json_data(dict)
+
+
+.. py:function:: return_path(input_path: piel.config.piel_path_types) -> pathlib.Path
+
+   Returns a pathlib.Path to be able to perform operations accordingly internally.
+
+   This allows us to maintain compatibility between POSIX and Windows systems.
+
+   :param input_path: Input path.
+   :type input_path: str
+
+   :returns: Pathlib path.
+   :rtype: pathlib.Path
+
+
+.. py:function:: run_script(script_path: piel.config.piel_path_types) -> None
+
+   Runs a script on the filesystem `script_path`.
+
+   :param script_path: Script path.
+   :type script_path: piel_path_types
+
+   :returns: None
+
+
+.. py:function:: setup_example_design(project_source: Literal[piel, openlane] = 'piel', example_name: str = 'simple_design') -> None
+
+   We copy the example simple_design from docs to the `/foss/designs` in the `iic-osic-tools` environment.
+
+   :param project_source: Source of the project.
+   :type project_source: str
+   :param example_name: Name of the example design.
+   :type example_name: str
+
+   :returns: None
+
+
+.. py:function:: write_script(directory_path: piel.config.piel_path_types, script: str, script_name: str) -> None
+
+   Records a `script_name` in the `scripts` project directory.
+
+   :param directory_path: Design directory.
+   :type directory_path: piel_path_types
+   :param script: Script to write.
+   :type script: str
+   :param script_name: Name of the script.
+   :type script_name: str
+
+   :returns: None