diff --git a/.gitignore b/.gitignore index 36631ad..c1f6d10 100644 --- a/.gitignore +++ b/.gitignore @@ -6,20 +6,32 @@ __pycache__/ .coverage .cov coverage.xml +/report/coverage + +# mypy +/report/typing + +# pytest +/report/unit # setuptools -/build/ -/dist/ +/build/**/*.* +/dist/**/*.* /*.egg-info # Dependencies !requirements.txt # Sphinx -/doc/_build/ -/doc/_theme/ -/doc/pySystemRDLModel/**/*.* -!/doc/pySystemRDLModel/index.rst +doc/_build/ +doc/pySystemRDLModel/**/*.* +!doc/pySystemRDLModel/index.rst -# PyCharm project files +# BuildTheDocs +doc/_theme/**/*.* + +# IntelliJ project files /.idea/workspace.xml + +# Git files +!.git* diff --git a/doc/Dependency.rst b/doc/Dependency.rst index 0481357..54f2eb1 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -1,30 +1,53 @@ -.. _dependency: +.. _DEP: -Dependency -########## +Dependencies +############ .. |img-pySystemRDLModel-lib-status| image:: https://img.shields.io/librariesio/release/pypi/pySystemRDLModel :alt: Libraries.io status for latest release :height: 22 :target: https://libraries.io/github/edaa-org/pySystemRDLModel -.. |img-pySystemRDLModel-req-status| image:: https://img.shields.io/requires/github/edaa-org/pySystemRDLModel - :alt: Requires.io +.. |img-pySystemRDLModel-vul-status| image:: https://img.shields.io/snyk/vulnerabilities/github/edaa-org/pySystemRDLModel + :alt: Snyk Vulnerabilities for GitHub Repo :height: 22 - :target: https://requires.io/github/edaa-org/pySystemRDLModel/requirements/?branch=main + :target: https://img.shields.io/snyk/vulnerabilities/github/edaa-org/pySystemRDLModel +------------------------------------------+------------------------------------------+ -| `Libraries.io `_ | `Requires.io `_ | +| `Libraries.io `_ | Vulnerabilities Summary | +==========================================+==========================================+ -| |img-pySystemRDLModel-lib-status| | |img-pySystemRDLModel-req-status| | +| |img-pySystemRDLModel-lib-status| | |img-pySystemRDLModel-vul-status| | +------------------------------------------+------------------------------------------+ +.. _DEP/package: -.. _dependency-package: +pySystemRDLModel Package (Mandatory) +************************************ -pySystemRDLModel Package -************************ +.. rubric:: Manually Installing Package Requirements -*None* +Use the :file:`requirements.txt` file to install all dependencies via ``pip3`` or install the package directly from +PyPI (see :ref:`INSTALL`). + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + pip3 install -U -r requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip install -U -r requirements.txt + + +.. rubric:: Dependency List + +When installed as ``pySystemRDLModel``: +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | **Package** | **Version** | **License** | **Dependencies** | @@ -33,10 +56,13 @@ pySystemRDLModel Package +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ -.. _dependency-testing: +.. _DEP/testing: + +Unit Testing (Optional) +*********************** Unit Testing / Coverage / Type Checking (Optional) -************************************************** +================================================== Additional Python packages needed for testing, code coverage collection and static type checking. These packages are only needed for developers or on a CI server, thus sub-dependencies are not evaluated further. @@ -47,17 +73,28 @@ only needed for developers or on a CI server, thus sub-dependencies are not eval Use the :file:`tests/requirements.txt` file to install all dependencies via ``pip3``. The file will recursively install the mandatory dependencies too. -.. code-block:: shell +.. tab-set:: - pip3 install -U -r tests/requirements.txt + .. tab-item:: Linux/macOS + :sync: Linux + .. code-block:: bash -.. rubric:: Dependency List + pip install -U -r tests/requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip3 install -U -r tests\requirements.txt + +.. rubric:: Dependency List - Unit Testing +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ | **Package** | **Version** | **License** | **Dependencies** | +=====================================================================+=============+========================================================================================+======================+ -| `pytest `__ | ≥8.3 | `MIT `__ | *Not yet evaluated.* | +| `pytest `__ | ≥8.3 | `MIT `__ | *Not yet evaluated.* | +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ | `pytest-cov `__ | ≥6.0 | `MIT `__ | *Not yet evaluated.* | +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ @@ -71,7 +108,7 @@ the mandatory dependencies too. +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ -.. _dependency-documentation: +.. _DEP/documentation: Sphinx Documentation (Optional) ******************************* @@ -85,9 +122,21 @@ CI server, thus sub-dependencies are not evaluated further. Use the :file:`doc/requirements.txt` file to install all dependencies via ``pip3``. The file will recursively install the mandatory dependencies too. -.. code-block:: shell +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux - pip3 install -U -r doc/requirements.txt + .. code-block:: bash + + pip install -U -r doc/requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip3 install -U -r doc\requirements.txt .. rubric:: Dependency List @@ -99,15 +148,21 @@ the mandatory dependencies too. +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `Sphinx `__ | ≥8.1 | `BSD 3-Clause `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `sphinxcontrib-mermaid `__ | ≥0.9.2 | `BSD `__ | *Not yet evaluated.* | ++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `autoapi `__ | ≥2.0.1 | `Apache License, 2.0 `__ | *Not yet evaluated.* | ++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `sphinx_btd_theme `__ | ≥0.5.2 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| !! `sphinx_fontawesome `__ | ≥0.0.6 | `GPL 2.0 `__ | *Not yet evaluated.* | +| `sphinx_design `__ | ≥0.6 | `MIT `__ | *Not yet evaluated.* | ++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `sphinx-copybutton `__ | ≥0.5 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `sphinx_autodoc_typehints `__ | ≥2.5 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -.. _dependency-packaging: +.. _DEP/packaging: Packaging (Optional) ******************** @@ -121,9 +176,21 @@ on a CI server, thus sub-dependencies are not evaluated further. Use the :file:`build/requirements.txt` file to install all dependencies via ``pip3``. The file will recursively install the mandatory dependencies too. -.. code-block:: shell +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash - pip3 install -U -r build/requirements.txt + pip install -U -r build/requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip3 install -U -r build\requirements.txt .. rubric:: Dependency List @@ -137,7 +204,7 @@ install the mandatory dependencies too. +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -.. _dependency-publishing: +.. _DEP/publishing: Publishing (CI-Server only) *************************** @@ -152,9 +219,21 @@ further. Use the :file:`dist/requirements.txt` file to install all dependencies via ``pip3``. The file will recursively install the mandatory dependencies too. -.. code-block:: shell +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + pip install -U -r dist/requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell - pip3 install -U -r dist/requirements.txt + pip3 install -U -r dist\requirements.txt .. rubric:: Dependency List diff --git a/doc/Doc-License.rst b/doc/Doc-License.rst index 1258fbc..ca0c256 100644 --- a/doc/Doc-License.rst +++ b/doc/Doc-License.rst @@ -1,8 +1,8 @@ .. _DOCLICENSE: -.. Note:: This is a local copy of the `Creative Commons - Attribution 4.0 International (CC BY 4.0) `__. +.. note:: This is a local copy of the `Creative Commons - Attribution 4.0 International (CC BY 4.0) `__. -.. Attention:: This **CC BY 4.0** license applies only to the **documentation** of this project. +.. attention:: This **CC BY 4.0** license applies only to the **documentation** of this project. Creative Commons Attribution 4.0 International diff --git a/doc/DocCoverage.rst b/doc/DocCoverage.rst new file mode 100644 index 0000000..c1e7526 --- /dev/null +++ b/doc/DocCoverage.rst @@ -0,0 +1,7 @@ +Documentation Coverage +###################### + +Documentation coverage generated by `docstr-coverage `__. + +.. report:doc-coverage:: + :packageid: src diff --git a/doc/Installation.rst b/doc/Installation.rst index 7615769..c71ba75 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -1,37 +1,484 @@ -.. _installation: +.. |PackageName| replace:: pySystemRDLModel + +.. _INSTALL: Installation/Updates #################### +See the following instructions on how to install or update the package from common sources like PyPI. Developers can +also install the packages with development dependencies. In case of local development, see the additional sections on +how to run unit tests, type checks or how to build the documentation to create all the build artifacts. + +See the list of :ref:`necessary dependencies `. + + +.. _INSTALL/pip: + +Using PIP to Install from PyPI +****************************** + +The following instruction are using PIP (Package Installer for Python) as a package manager and PyPI (Python Package +Index) as a source of Python packages. + +PIP might download further packages as listed in :ref:`package dependencies `. + + +.. _INSTALL/pip/install: + +Installing a Wheel Package from PyPI using PIP +============================================== + +Developers can install further dependencies for documentation generation (``doc``) or running unit tests (``test``) or +just all (``all``) dependencies. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. tab-set:: + + .. tab-item:: Minimal installation + :sync: Minimal + + .. code-block:: bash + + # Basic pySystemRDLModel package + pip3 install pySystemRDLModel + + # Alternatively + python3 -m pip install pySystemRDLModel + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: bash + + # Install with dependencies to generate documentation + pip3 install pySystemRDLModel[doc] + + # Alternatively + python3 -m pip install pySystemRDLModel[doc] + + .. tab-item:: With Unit Testing Dependencies + :sync: Unit + + .. code-block:: bash + + # Install with dependencies to run unit tests + pip3 install pySystemRDLModel[test] + + # Alternatively + python3 -m pip install pySystemRDLModel[test] + + .. tab-item:: All Developer Dependencies + :sync: All + + .. code-block:: bash + + # Install with all developer dependencies + pip3 install pySystemRDLModel[all] + + # Alternatively + python3 -m pip install pySystemRDLModel[all] + + .. tab-item:: Windows + :sync: Windows + + .. tab-set:: + + .. tab-item:: Minimal installation + :sync: Minimal + + .. code-block:: powershell + + # Basic pySystemRDLModel package + pip install pySystemRDLModel + + # Alternatively + py -m pip install pySystemRDLModel + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: powershell + + # Install with dependencies to generate documentation + pip install pySystemRDLModel[doc] + + # Alternatively + py -m pip install pySystemRDLModel[doc] + + .. tab-item:: With Unit Testing Dependencies + :sync: Unit + + .. code-block:: powershell + + # Install with dependencies to run unit tests + pip install pySystemRDLModel[test] + + # Alternatively + py -m pip install pySystemRDLModel[test] + + .. tab-item:: All Developer Dependencies + :sync: All + + .. code-block:: powershell + + # Install with all developer dependencies + pip install pySystemRDLModel[all] + + # Alternatively + py -m pip install pySystemRDLModel[all] + + +.. _INSTALL/pip/requirements: + +Referencing the package in ``requirements.txt`` +=============================================== + +When |PackageName| is used by another Python package, it's recommended to list the dependency to the |PackageName| +package in a ``requirements.txt`` file. + +.. admonition:: ``requirements.txt`` + + .. code-block:: text + + pySystemRDLModel ~= 0.3 + + +.. _INSTALL/pip/update: + +Updating from PyPI using PIP +============================ + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + # Update pySystemRDLModel + pip3 install -U pySystemRDLModel + + # Alternatively + python3 -m pip install -U pySystemRDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + # Update pySystemRDLModel + pip install -U pySystemRDLModel + + # Alternatively + py -m pip install -U pySystemRDLModel + + +.. _INSTALL/pip/uninstall: + +Uninstallation using PIP +======================== + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + # Uninstall pySystemRDLModel + pip3 uninstall pySystemRDLModel + + # Alternatively + python3 -m pip uninstall pySystemRDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + # Uninstall pySystemRDLModel + pip uninstall pySystemRDLModel + + # Alternatively + py -m pip uninstall pySystemRDLModel + + +.. _INSTALL/testing: + +Running unit tests +****************** + +This package is provided with unit tests for `pytest `__. The provided testcases can be +executed locally for testing or development purposes. In addition, code coverage including branch coverage can be +collected using `Coverage.py `__. All steps provide appropriate artifacts as XML or +HTML reports. The artifact output directories are specified in ``pyproject.toml``. + +Ensure :ref:`unit testing requirements ` are installed. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. tab-set:: + + .. tab-item:: Unit Testing + :sync: UnitTesting + + .. code-block:: bash + + cd + + # Running unit tests using pytest + pytest -raP --color=yes tests/unit + + .. tab-item:: Unit Testing with Ant/JUnit XML Reports + :sync: UnitTestingXML + + .. code-block:: bash + + cd + + # Running unit tests using pytest + pytest -raP --color=yes --junitxml=report/unit/unittest.xml --template=html1/index.html --report=report/unit/html/index.html --split-report tests/unit + + .. tab-item:: Unit Testing with Code Coverage + :sync: Coverage + + .. code-block:: bash + + cd + + # Running unit tests with code coverage using Coverage.py + coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests/unit + + # Write coverage report to console" + coverage report + + # Convert coverage report to HTML + coverage html + + # Convert coverage report to XML (Cobertura) + coverage xml + + .. tab-item:: Windows + :sync: Windows + + .. tab-set:: + + .. tab-item:: Unit Testing + :sync: UnitTesting + + .. code-block:: powershell + + cd + + # Running unit tests using pytest + pytest -raP --color=yes tests\unit + + .. tab-item:: Unit Testing with Ant/JUnit XML Reports + :sync: UnitTestingXML + + .. code-block:: powershell + + cd + + # Running unit tests using pytest + pytest -raP --color=yes --junitxml=report\unit\unittest.xml --template=html1\index.html --report=report\unit\html\index.html --split-report tests\unit + + .. tab-item:: Unit Testing with Code Coverage + :sync: Coverage + + .. code-block:: powershell + + cd + + # Running unit tests with code coverage using Coverage.py + coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests\unit + + # Write coverage report to console" + coverage report + + # Convert coverage report to HTML + coverage html + + # Convert coverage report to XML (Cobertura) + coverage xml + + +.. _INSTALL/typechecking: + +Running type checks +******************* + +This package is provided with type checks. These can be executed locally for testing or development purposes using +`mypy `__. The artifact output directory is specified in ``pyproject.toml``. + +Ensure :ref:`unit testing requirements ` are installed. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + cd + + # Running type checking using mypy + export MYPY_FORCE_COLOR=1 + mypy -p pySystemRDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + cd + + # Running type checking using mypy + $env:MYPY_FORCE_COLOR = 1 + mypy -p pySystemRDLModel + + +.. _INSTALL/documentation: + +Building documentation +********************** + +The documentation can be build locally using `Sphinx `__. It can generate HTML and LaTeX +outputs. In an additional step, the LaTeX output can be translated to a PDF file using a LaTeX environment like +`MiKTeX `__. + +Ensure :ref:`documentation requirements ` are installed. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. tab-set:: + + .. tab-item:: Generating HTML + :sync: HTML + + .. code-block:: bash + + cd + + # Adding package root to PYTHONPATH + export PYTHONPATH=$(pwd) + cd doc + + # Building documentation using Sphinx + sphinx-build -v -n -b html -d _build/doctrees -j $(nproc) -w _build/html.log . _build/html + + .. tab-item:: Generating LaTeX + :sync: LaTeX + + .. code-block:: bash + + cd + + # Adding package root to PYTHONPATH + export PYTHONPATH=$(pwd) + cd doc + + # Building documentation using Sphinx + sphinx-build -v -n -b latex -d _build/doctrees -j $(nproc) -w _build/latex.log . _build/latex + + .. tab-item:: Generating PDF (from LaTeX) + :sync: PDF + + .. todo:: Describe LaTeX to PDF conversion on Linux using Miktex. + + .. hint:: A `Miktex installation `__ is required. + + .. tab-item:: Windows + :sync: Windows + + .. tab-set:: + + .. tab-item:: Generating HTML + :sync: HTML + + .. code-block:: powershell + + cd + + # Building documentation using Sphinx + .\doc\make.bat html --verbose + + .. tab-item:: Generating LaTeX + :sync: LaTeX + + .. code-block:: powershell + + cd + + # Building documentation using Sphinx + .\doc\make.bat latex --verbose + + .. tab-item:: Generating PDF (from LaTeX) + :sync: PDF + + .. todo:: Describe LaTeX to PDF conversion on Windows using Miktex. + + .. hint:: A `Miktex installation `__ is required. + + +.. _INSTALL/building: + +Local Packaging and Installation via PIP +**************************************** + +For development and bug fixing it might be handy to create a local wheel package and also install it locally on the +development machine. The following instructions will create a local wheel package (``*.whl``) and then use PIP to +install it. As a user might have a |PackageName| installation from PyPI, it's recommended to uninstall any previous +|PackageName| packages. (This step is also needed if installing an updated local wheel file with same version number. +PIP will not detect a new version and thus not overwrite/reinstall the updated package contents.) +Ensure :ref:`packaging requirements ` are installed. -.. _installation-pip: +.. tab-set:: -Using PIP -********* + .. tab-item:: Linux/macOS + :sync: Linux -Installation using PIP -====================== + .. code-block:: bash -.. code-block:: bash + cd - pip3 install pySystemRDLModel + # Package the code in a wheel (*.whl) + python3 -m build --wheel + # Uninstall the old package + python3 -m pip uninstall -y pySystemRDLModel -Updating using PIP -================== + # Install from wheel + python3 -m pip install ./dist/pySystemRDLModel-0.3.1-py3-none-any.whl -.. code-block:: bash + .. tab-item:: Windows + :sync: Windows - pip3 install -U pySystemRDLModel + .. code-block:: powershell + cd + # Package the code in a wheel (*.whl) + py -m build --wheel -.. _installation-setup: + # Uninstall the old package + py -m pip uninstall -y pySystemRDLModel -Using setup.py -************** + # Install from wheel + py -m pip install .\dist\pySystemRDLModel-0.3.1-py3-none-any.whl -.. todo:: +.. note:: - Describe setup procedure using ``setup.py`` + The legacy ways of building a package using ``setup.py bdist_wheel`` and installation using ``setup.py install`` is + not recommended anymore. diff --git a/doc/License.rst b/doc/License.rst index fba66a2..a6ed1d9 100644 --- a/doc/License.rst +++ b/doc/License.rst @@ -1,8 +1,8 @@ .. _SRCLICENSE: -.. Note:: This is a local copy of the `Apache License Version 2.0 `__. +.. note:: This is a local copy of the `Apache License Version 2.0 `__. -.. Attention:: This **Apache License, 2.0** applies to all **source and configuration files of project**, **except documentation**. +.. attention:: This **Apache License, 2.0** applies to all **source and configuration files of project**, **except documentation**. Apache License 2.0 ################## diff --git a/doc/TODO.rst b/doc/TODO.rst new file mode 100644 index 0000000..3144da0 --- /dev/null +++ b/doc/TODO.rst @@ -0,0 +1,4 @@ +TODOs +##### + +.. todolist:: diff --git a/doc/_static/css/override.css b/doc/_static/css/override.css new file mode 100644 index 0000000..4dd6beb --- /dev/null +++ b/doc/_static/css/override.css @@ -0,0 +1,115 @@ +/* theme overrides */ +.rst-content h1, +.rst-content h2 { + margin-top: 24px; + margin-bottom: 6px; + text-decoration: underline; +} + +.rst-content h3, +.rst-content h4, +.rst-content h5, +.rst-content h6 { + margin-top: 12px; + margin-bottom: 6px; +} + +.rst-content p { + margin-bottom: 6px +} + +.rst-content .topic-title { + font-size: larger; + font-weight: 700; + margin-top: 18px; + margin-bottom: 6px; +} + +.rst-content p.rubric { + text-decoration: underline; + font-weight: 700; + margin-top: 18px; + margin-bottom: 16px; +} + +/* general overrides */ +html { + font-size: 15px; +} + +footer { + font-size: 95%; + text-align: center +} + +footer p { + margin-bottom: 0px /* 12px */; + font-size: 95% +} + +section > p, +.section p, +.simple li { + text-align: justify +} + +/* wyrm overrides */ +.wy-menu-vertical header, +.wy-menu-vertical p.caption { + color: #9b9b9b /* #55a5d9 */; + padding: 0 0.809em /* 0 1.618em */; + margin: 6px 0 0 0 /* 12px 0 0 */; + border-top: 1px solid #9b9b9b; +} + +.wy-side-nav-search { + margin-bottom: 0 /* .809em */; + background-color: #333333 /* #2980b9 */; + /* BTD: */ + /*color: #fcfcfc*/ +} + +.wy-side-nav-search input[type=text] { + border-radius: 0px /* 50px */; +} + +.wy-side-nav-search .wy-dropdown > a, .wy-side-nav-search > a { + /* BTD: */ + /*color: #fcfcfc;*/ + margin-bottom: 0.404em /* .809em */; +} + +.wy-side-nav-search > div.version { + margin: 0 0 6px 0; + /* BTD: */ + /*margin-top: -.4045em;*/ +} + +.wy-nav .wy-menu-vertical a:hover { + background-color: #333333 /* #2980b9 */; +} + +.wy-nav-content { + max-width: 1600px /* 800px */ ; +} + +.wy-nav-top { + background: #333333 /* #2980b9 */; +} + +/* Sphinx Design */ +.sd-tab-set { + margin: 0 +} + +.sd-tab-set > label { + padding-top: .5em; + padding-right: 1em; + padding-bottom: .5em; + padding-left: 1em +} + +.sd-container-fluid { + padding-left: 0; + padding-right: 0; +} diff --git a/doc/_templates/autoapi/module.rst b/doc/_templates/autoapi/module.rst index 655beff..4dded81 100644 --- a/doc/_templates/autoapi/module.rst +++ b/doc/_templates/autoapi/module.rst @@ -1,12 +1,12 @@ -.. # Template modified by Patrick Lehmann +.. # Template modified by Patrick Lehmann * removed automodule on top, because private members are activated for autodoc (no doubled documentation). * Made sections like 'submodules' bold text, but no headlines to reduce number of ToC levels. -=={{ '=' * node.name|length }}== -``{{ node.name }}`` -=={{ '=' * node.name|length }}== +{{ '=' * node.name|length }} +{{ node.name }} +{{ '=' * node.name|length }} -.. py:module:: {{ node.name }} +.. automodule:: {{ node.name }} {##} {%- block modules -%} @@ -14,8 +14,8 @@ **Submodules** - .. toctree:: + :maxdepth: 1 {% for item in subnodes %} {{ item.name }} {%- endfor %} @@ -25,7 +25,17 @@ {##} .. currentmodule:: {{ node.name }} {##} -{%- block functions -%} + +{%- if node.variables %} + +**Variables** + +{% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` + {#{ obj|summary }#} +{% endfor -%} +{%- endif -%} + {%- if node.functions %} **Functions** @@ -35,15 +45,19 @@ {{ obj|summary }} {% endfor -%} +{%- endif -%} -{% for item in node.functions %} -.. autofunction:: {{ item }} -{##} -{%- endfor -%} +{%- if node.exceptions %} + +**Exceptions** + +{% for item, obj in node.exceptions.items() -%} +- :py:exc:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%} {%- endif -%} -{%- endblock -%} -{%- block classes -%} {%- if node.classes %} **Classes** @@ -53,14 +67,40 @@ {{ obj|summary }} {% endfor -%} +{%- endif -%} -{% for item in node.classes %} -.. autoclass:: {{ item }} - :members: +{%- block variables -%} +{%- if node.variables %} - .. rubric:: Inheritance - .. inheritance-diagram:: {{ item }} - :parts: 1 +--------------------- + +**Variables** + +{#% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` +{% endfor -%#} + +{% for item, obj in node.variables.items() %} +.. autodata:: {{ item }} + :annotation: + + .. code-block:: text + + {{ obj|pprint|indent(6) }} +{##} +{%- endfor -%} +{%- endif -%} +{%- endblock -%} + +{%- block functions -%} +{%- if node.functions %} + +--------------------- + +**Functions** + +{% for item in node.functions %} +.. autofunction:: {{ item }} {##} {%- endfor -%} {%- endif -%} @@ -69,13 +109,15 @@ {%- block exceptions -%} {%- if node.exceptions %} +--------------------- + **Exceptions** -{% for item, obj in node.exceptions.items() -%} +{#% for item, obj in node.exceptions.items() -%} - :py:exc:`{{ item }}`: {{ obj|summary }} -{% endfor -%} +{% endfor -%#} {% for item in node.exceptions %} .. autoexception:: {{ item }} @@ -88,22 +130,30 @@ {%- endif -%} {%- endblock -%} -{%- block variables -%} -{%- if node.variables %} +{%- block classes -%} +{%- if node.classes %} -**Variables** +--------------------- -{% for item, obj in node.variables.items() -%} -- :py:data:`{{ item }}` -{% endfor -%} +**Classes** -{% for item, obj in node.variables.items() %} -.. autodata:: {{ item }} - :annotation: +{#% for item, obj in node.classes.items() -%} +- :py:class:`{{ item }}`: + {{ obj|summary }} - .. code-block:: text +{% endfor -%#} - {{ obj|pprint|indent(6) }} +{% for item in node.classes %} +.. autoclass:: {{ item }} + :members: + :private-members: + :special-members: + :inherited-members: + :exclude-members: __weakref__ + + .. rubric:: Inheritance + .. inheritance-diagram:: {{ item }} + :parts: 1 {##} {%- endfor -%} {%- endif -%} diff --git a/doc/_templates/autoapi/package.rst b/doc/_templates/autoapi/package.rst new file mode 100644 index 0000000..9cc9fbd --- /dev/null +++ b/doc/_templates/autoapi/package.rst @@ -0,0 +1,14 @@ +.. # Template created by Patrick Lehmann + +Python Class Reference +###################### + +Reference of all packages and modules: + +.. automodule:: {{ node.name }} + +.. toctree:: + :maxdepth: 1 +{% for item in subnodes %} + {{ item.name }} +{%- endfor %} diff --git a/doc/conf.py b/doc/conf.py index f517b2c..1c4f008 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,19 +1,17 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. - from sys import path as sys_path from os.path import abspath from pathlib import Path -from json import loads from pyTooling.Packaging import extractVersionInformation ROOT = Path(__file__).resolve().parent -sys_path.insert(0, abspath('.')) -sys_path.insert(0, abspath('..')) -sys_path.insert(0, abspath('../pySystemRDLModel')) +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) +sys_path.insert(0, abspath("../pySystemRDLModel")) # ============================================================================== @@ -22,7 +20,8 @@ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -project = "pySystemRDLModel" +githubNamespace = "edaa-org" +project = "pySystemRDLModel" packageInformationFile = Path(f"../{project.replace('.', '/')}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) @@ -37,23 +36,23 @@ # Miscellaneous settings # ============================================================================== # The master toctree document. -master_doc = 'index' +master_doc = "index" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ "_build", - "_themes", + "_theme", "Thumbs.db", ".DS_Store" ] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'stata-dark' +pygments_style = "manni" # ============================================================================== @@ -72,39 +71,38 @@ # ============================================================================== # Options for HTML output # ============================================================================== - -html_context = {} -ctx = ROOT / 'context.json' -if ctx.is_file(): - html_context.update(loads(ctx.open('r').read())) - -if (ROOT / "_theme").is_dir(): - html_theme_path = ["."] - html_theme = "_theme" - html_theme_options = { - 'logo_only': True, - 'home_breadcrumbs': False, - 'vcs_pageview_mode': 'blob', - } -else: - html_theme = "alabaster" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "logo_only": True, + "vcs_pageview_mode": 'blob', + "navigation_depth": 5, +} +html_css_files = [ + 'css/override.css', +] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] html_logo = str(Path(html_static_path[0]) / "logo.svg") html_favicon = str(Path(html_static_path[0]) / "favicon.svg") # Output file base name for HTML help builder. -htmlhelp_basename = 'pySystemRDLModelDoc' +htmlhelp_basename = f"{project}Doc" # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. # The empty string is equivalent to '%b %d, %Y'. html_last_updated_fmt = "%d.%m.%Y" +# ============================================================================== +# Python settings +# ============================================================================== +modindex_common_prefix = [ + f"{project}." +] # ============================================================================== # Options for LaTeX / PDF output @@ -113,13 +111,13 @@ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). - 'papersize': 'a4paper', + "papersize": "a4paper", # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. - 'preamble': dedent(r""" + "preamble": dedent(r""" % ================================================================================ % User defined additional preamble code % ================================================================================ @@ -145,10 +143,10 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - 'pySystemRDLModel.tex', - 'The pySystemRDLModel Documentation', - 'Patrick Lehmann', - 'manual' + f"{project}.tex", + f"The {project} Documentation", + f"Patrick Lehmann", + f"manual" ), ] @@ -159,27 +157,32 @@ extensions = [ # Standard Sphinx extensions "sphinx.ext.autodoc", - 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.todo', - 'sphinx.ext.graphviz', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.inheritance_diagram", + "sphinx.ext.todo", + "sphinx.ext.graphviz", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", # SphinxContrib extensions - 'sphinxcontrib.mermaid', + "sphinxcontrib.mermaid", # Other extensions - 'sphinx_fontawesome', - 'sphinx_autodoc_typehints', - 'autoapi.sphinx', + "sphinx_design", + "sphinx_copybutton", + "sphinx_autodoc_typehints", + "autoapi.sphinx", + "sphinx_reports", +# User defined extensions ] + # ============================================================================== # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3', None), + "python": ("https://docs.python.org/3", None), + "setup": ("https://setuptools.pypa.io/en/latest", None), } @@ -187,26 +190,27 @@ # Sphinx.Ext.AutoDoc # ============================================================================== # see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration -autodoc_default_options = { - "private-members": True, - "special-members": True, - "inherited-members": True, - "exclude-members": "__weakref__" -} +#autodoc_default_options = { +# "private-members": True, +# "special-members": True, +# "inherited-members": True, +# "exclude-members": "__weakref__" +#} #autodoc_class_signature = "separated" autodoc_member_order = "bysource" # alphabetical, groupwise, bysource autodoc_typehints = "both" #autoclass_content = "both" - # ============================================================================== # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - "ghissue": ('https://GitHub.com/edaa-org/pySystemRDLModel/issues/%s', 'issue #%s'), - "ghpull": ('https://GitHub.com/edaa-org/pySystemRDLModel/pull/%s', 'pull request #%s'), - "ghsrc": ('https://GitHub.com/edaa-org/pySystemRDLModel/blob/main/%s?ts=2', None), + "gh": (f"https://GitHub.com/%s", "gh:%s"), + "ghissue": (f"https://GitHub.com/{githubNamespace}/{project}/issues/%s", "issue #%s"), + "ghpull": (f"https://GitHub.com/{githubNamespace}/{project}/pull/%s", "pull request #%s"), + "ghsrc": (f"https://GitHub.com/{githubNamespace}/{project}/blob/main/%s", None), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), } @@ -216,6 +220,26 @@ graphviz_output_format = "svg" +# ============================================================================== +# SphinxContrib.Mermaid +# ============================================================================== +mermaid_params = [ + '--backgroundColor', 'transparent', +] +mermaid_verbose = True + + +# ============================================================================== +# Sphinx.Ext.Inheritance_Diagram +# ============================================================================== +inheritance_node_attrs = { +# "shape": "ellipse", +# "fontsize": 14, +# "height": 0.75, + "color": "dodgerblue1", + "style": "filled" +} + # ============================================================================== # Sphinx.Ext.ToDo @@ -225,10 +249,46 @@ todo_link_only = True +# ============================================================================== +# sphinx-reports +# ============================================================================== +report_unittest_testsuites = { + "src": { + "name": f"{project}", + "xml_report": "../report/unit/unittest.xml", + } +} +report_codecov_packages = { + "src": { + "name": f"{project}", + "json_report": "../report/coverage/coverage.json", + "fail_below": 80, + "levels": "default" + } +} +report_doccov_packages = { + "src": { + "name": f"{project}", + "directory": f"../{project}", + "fail_below": 80, + "levels": "default" + } +} + + +# ============================================================================== +# Sphinx_Design +# ============================================================================== +# sd_fontawesome_latex = True + # ============================================================================== # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - 'pySystemRDLModel': {'output': "pySystemRDLModel", "override": True} + f"{project}": { + "template": "module", + "output": project, + "override": True + } } diff --git a/doc/coverage/index.rst b/doc/coverage/index.rst index 80bbad2..331173f 100644 --- a/doc/coverage/index.rst +++ b/doc/coverage/index.rst @@ -1,4 +1,8 @@ -Coverage Report -############### +Code Coverage Report +#################### -*Placeholder for the Coverage report generated with* ``pytest`` *and* ``coverage``. +Code coverage report generated with `pytest `__ and `Coverage.py `__. + + +.. report:code-coverage:: + :packageid: src diff --git a/doc/genindex.rst b/doc/genindex.rst deleted file mode 100644 index c07da40..0000000 --- a/doc/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. This file is a placeholder and will be replaced - -Index -##### diff --git a/doc/index.rst b/doc/index.rst index 433b40b..37cf6ee 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -97,13 +97,6 @@ License This Python package (source code) is licensed under **Apache License 2.0**. |br| The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**. ------------------------------------- - -.. |docdate| date:: %d.%b %Y - %H:%M - -.. only:: html - - This document was generated on |docdate|. .. toctree:: :hidden: @@ -117,7 +110,6 @@ License Installation Dependency - .. raw:: latex \part{Main Documentation} @@ -131,14 +123,17 @@ License .. raw:: latex - \part{References} + \part{References and Reports} .. toctree:: - :caption: References + :caption: References and Reports :hidden: - pySystemRDLModel/index - + pySystemRDLModel/pySystemRDLModel + unittests/index + coverage/index + Doc. Coverage Report + Static Type Check Report ➚ .. raw:: latex @@ -148,12 +143,9 @@ License :caption: Appendix :hidden: - Coverage Report ➚ - Static Type Check Report ➚ License Doc-License Glossary genindex - -.. # - py-modindex + Python Module Index + TODO diff --git a/doc/py-modindex.rst b/doc/py-modindex.rst deleted file mode 100644 index 23167be..0000000 --- a/doc/py-modindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. This file is a placeholder and will be replaced - -Module Index -############ diff --git a/doc/pySystemRDLModel/index.rst b/doc/pySystemRDLModel/index.rst deleted file mode 100644 index 1c3e618..0000000 --- a/doc/pySystemRDLModel/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Python Class Reference -###################### - -Reference of all packages and modules: - -.. toctree:: - - pySystemRDLModel diff --git a/doc/requirements.txt b/doc/requirements.txt index 67860f4..2d35335 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,8 +5,15 @@ sphinx ~= 8.1 docutils ~= 0.21 docutils_stubs ~= 0.0.22 +# ReadTheDocs Theme +sphinx_rtd_theme ~= 3.0.0 + # Sphinx Extenstions sphinxcontrib-mermaid ~= 1.0 -autoapi>=2.0.1 -sphinx_fontawesome>=0.0.6 +autoapi >= 2.0.1 +sphinx_design ~= 0.6.1 +sphinx-copybutton >= 0.5.2 sphinx_autodoc_typehints ~= 2.5 +sphinx_reports ~= 0.7 + +# BuildTheDocs Extensions (mostly patched Sphinx extensions) diff --git a/doc/unittests/index.rst b/doc/unittests/index.rst new file mode 100644 index 0000000..8b840ee --- /dev/null +++ b/doc/unittests/index.rst @@ -0,0 +1,7 @@ +Unittest Summary Report +####################### + +Unittest report generated with `pytest `__. + +.. report:unittest-summary:: + :reportid: src diff --git a/pySystemRDLModel/__init__.py b/pySystemRDLModel/__init__.py index 300a05f..391180d 100644 --- a/pySystemRDLModel/__init__.py +++ b/pySystemRDLModel/__init__.py @@ -29,10 +29,18 @@ # ==================================================================================================================== # # """ -An abstract SystemRDL language model. +**An abstract SystemRDL language model.** -:copyright: Copyright 2023-2024 Patrick Lehmann - Bötzingen, Germany -:license: Apache License, Version 2.0 +This package provides a unified abstract language model for SystemRDL. Projects reading from source files can derive own +classes and implement additional logic to create a concrete language model for their tools. + +Projects consuming pre-processed SystemRDL data can build higher level features and services on such a model, while +supporting multiple frontends. + +.. admonition:: Copyright Information + + :copyright: Copyright 2023-2024 Patrick Lehmann - Bötzingen, Germany + :license: Apache License, Version 2.0 """ from enum import unique, Enum from typing import Dict, Union @@ -50,12 +58,20 @@ @export @unique class SystemRDLVersion(Enum): - Any = -1 + """ + An enumeration for all possible version numbers for SystemRDL. + + A version can be given as integer or string and is represented as a unified + enumeration value. - SystemRDL2005 = 2005 - SystemRDL2009 = 2009 - SystemRDL2012 = 2012 - SystemRDL2017 = 2017 + This enumeration supports compare operators. + """ + Any = -1 #: Any + + SystemRDL2005 = 2005 #: SystemRDL-2005 + SystemRDL2009 = 2009 #: SystemRDL-2009 + SystemRDL2012 = 2012 #: SystemRDL-2012 + SystemRDL2017 = 2017 #: SystemRDL-2017 Latest = 10000 @@ -80,7 +96,7 @@ class SystemRDLVersion(Enum): "2012": SystemRDL2012, "2017": SystemRDL2017, "Latest": SystemRDL2017, - } + } #: Dictionary of SystemRDL year codes variants as integer and strings for mapping to unique enum values. def __init__(self, *_): """Patch the embedded MAP dictionary""" @@ -91,6 +107,13 @@ def __init__(self, *_): @classmethod def Parse(cls, value: Union[int, str]) -> "SystemRDLVersion": + """ + Parses a SystemRDL year code as integer or string to an enum value. + + :param value: VHDL/VHDL-AMS year code. + :returns: Enumeration value. + :raises ValueError: If the year code is not recognized. + """ try: return cls.__VERSION_MAPPINGS__[value] except KeyError: @@ -98,7 +121,7 @@ def Parse(cls, value: Union[int, str]) -> "SystemRDLVersion": def __lt__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is less than the second operand. + Compare two SystemRDL versions if the version is less than the second operand. :param other: Parameter to compare against. :returns: True if version is less than the second operand. @@ -111,7 +134,7 @@ def __lt__(self, other: Any) -> bool: def __le__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is less or equal than the second operand. + Compare two SystemRDL versions if the version is less or equal than the second operand. :param other: Parameter to compare against. :returns: True if version is less or equal than the second operand. @@ -124,7 +147,7 @@ def __le__(self, other: Any) -> bool: def __gt__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is greater than the second operand. + Compare two SystemRDL versions if the version is greater than the second operand. :param other: Parameter to compare against. :returns: True if version is greater than the second operand. @@ -137,7 +160,7 @@ def __gt__(self, other: Any) -> bool: def __ge__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is greater or equal than the second operand. + Compare two SystemRDL versions if the version is greater or equal than the second operand. :param other: Parameter to compare against. :returns: True if version is greater or equal than the second operand. @@ -150,7 +173,7 @@ def __ge__(self, other: Any) -> bool: def __ne__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is unequal to the second operand. + Compare two SystemRDL versions if the version is unequal to the second operand. :param other: Parameter to compare against. :returns: True if version is unequal to the second operand. @@ -163,7 +186,7 @@ def __ne__(self, other: Any) -> bool: def __eq__(self, other: Any) -> bool: """ - Compare two (System)Verilog versions if the version is equal to the second operand. + Compare two SystemRDL versions if the version is equal to the second operand. :param other: Parameter to compare against. :returns: True if version is equal to the second operand. diff --git a/pyproject.toml b/pyproject.toml index 46316f8..d2e3d4b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [build-system] requires = [ - "setuptools ~= 75.3", + "setuptools ~= 75.4", "wheel ~= 0.45", "pyTooling ~= 8.0" ] @@ -30,7 +30,6 @@ filterwarnings = [ "error::DeprecationWarning", "error::PendingDeprecationWarning" ] -junit_logging = "all" [tool.interrogate] color = true diff --git a/run.ps1 b/run.ps1 new file mode 100644 index 0000000..0ba42f3 --- /dev/null +++ b/run.ps1 @@ -0,0 +1,316 @@ +[CmdletBinding()] +Param( + # Clean up all files and directories + [switch]$clean, + + # Commands + [switch]$all, + [switch]$copyall, + + [switch]$doc, + [switch]$livedoc, + [switch]$doccov, + + [switch]$unit, + [switch]$liveunit, + [switch]$copyunit, + + [switch]$cov, + [switch]$livecov, + [switch]$copycov, + + [switch]$type, + [switch]$livetype, + [switch]$copytype, + + [switch]$nooutput, + + [switch]$build, + [switch]$install, + + # Display this help" + [switch]$help +) + +$PackageName = "pySystemRDLModel" + +# set default values +$EnableDebug = [bool]$PSCmdlet.MyInvocation.BoundParameters["Debug"] +$EnableVerbose = [bool]$PSCmdlet.MyInvocation.BoundParameters["Verbose"] -or $EnableDebug + +# Display help if no command was selected +$help = $help -or ( -not( + $all -or $copyall -or + $clean -or + $doc -or $livedoc -or $doccov -or + $unit -or $liveunit -or $copyunit -or + $cov -or $livecov -or $copycov -or + $type -or $livetype -or $copytype -or + $build -or $install + ) +) + +Write-Host "================================================================================" -ForegroundColor Magenta +Write-Host "$PackageName Documentation Compilation and Assembly Tool" -ForegroundColor Magenta +Write-Host "================================================================================" -ForegroundColor Magenta + +if ($help) +{ Get-Help $MYINVOCATION.MyCommand.Path -Detailed + exit 0 +} + +if ($all) +{ $doc = $true + $unit = $true +# $copyunit = $true + $cov = $true +# $copycov = $true + $type = $true + $copytype = $true +} +if ($copyall) +{# $copyunit = $true +# $copycov = $true + $copytype = $true +} + +if ($clean) +{ Write-Host -ForegroundColor DarkYellow "[live][DOC] Cleaning documentation directories ..." + rm -Force .\doc\$PackageName\* + .\doc\make.bat clean + Write-Host -ForegroundColor DarkYellow "[live][BUILD] Cleaning build directories ..." + rm -Force .\build\bdist.win-amd64 + rm -Force .\build\lib +} + +if ($build) +{ Write-Host -ForegroundColor Yellow "[live][BUILD] Cleaning build directories ..." + rm -Force .\build\bdist.win-amd64 + rm -Force .\build\lib + Write-Host -ForegroundColor Yellow "[live][BUILD] Building $PackageName package as wheel ..." + py -3.12 -m build --wheel + + Write-Host -ForegroundColor Yellow "[live][BUILD] Building wheel finished" +} +if ($install) +{ if (!([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")) + { Write-Host -ForegroundColor Yellow "[live][INSTALL] Installing $PackageName with administrator rights ..." + $proc = Start-Process pwsh.exe "-NoProfile -ExecutionPolicy Bypass -WorkingDirectory `"$PSScriptRoot`" -File `"$PSCommandPath`" `"-install`"" -Verb RunAs -Wait + +# Write-Host -ForegroundColor Yellow "[live][INSTALL] Wait on administrator console ..." +# Wait-Process -Id $proc.Id + } + else + { Write-Host -ForegroundColor Cyan "[ADMIN][UNINSTALL] Uninstalling $PackageName ..." + py -3.12 -m pip uninstall -y $PackageName + Write-Host -ForegroundColor Cyan "[ADMIN][INSTALL] Installing $PackageName from wheel ..." + py -3.12 -m pip install .\dist\$PackageName-6.7.0-py3-none-any.whl + + Write-Host -ForegroundColor Cyan "[ADMIN][INSTALL] Closing window in 5 seconds ..." + Start-Sleep -Seconds 5 + } +} + +$jobs = @() + +if ($livedoc) +{ Write-Host -ForegroundColor DarkYellow "[live][DOC] Building documentation using Sphinx ..." + + .\doc\make.bat html --verbose + + Write-Host -ForegroundColor DarkYellow "[live][DOC] Documentation finished" +} +elseif ($doc) +{ Write-Host -ForegroundColor DarkYellow "[Job1][DOC] Building documentation using Sphinx ..." + Write-Host -ForegroundColor DarkGreen "[SCRIPT] Starting Documentation job ..." + + # Compile documentation + $compileDocFunc = { + .\doc\make.bat html --verbose + } + $docJob = Start-Job -Name "Documentation" -ScriptBlock $compileDocFunc +# $jobs += $docJob +} + + +if ($doccov) +{ + .\doc\make.bat coverage +} + +if ($liveunit) +{ Write-Host -ForegroundColor DarkYellow "[live][UNIT] Running Unit Tests using pytest ..." + + $env:ENVIRONMENT_NAME = "Windows (x86-64)" + pytest -raP --color=yes --junitxml=report/unit/unittest.xml --template=html1/index.html --report=report/unit/html/index.html --split-report tests/unit + + if ($copyunit) + { cp -Recurse -Force .\report\unit\html\* .\doc\_build\html\unittests + Write-Host -ForegroundColor DarkBlue "[live][UNIT] Copyed unit testing report to 'unittests' directory in HTML directory" + } + + Write-Host -ForegroundColor DarkYellow "[live][UNIT] Unit Tests finished" +} +elseif ($unit) +{ Write-Host -ForegroundColor DarkYellow "[Job2][UNIT] Running Unit Tests using pytest ..." + Write-Host -ForegroundColor DarkGreen "[SCRIPT] Starting UnitTests jobs ..." + + # Run unit tests + $runUnitFunc = { + $env:ENVIRONMENT_NAME = "Windows (x86-64)" + pytest -raP --color=yes --junitxml=report/unit/unittest.xml --template=html1/index.html --report=report/unit/html/index.html --split-report tests/unit + } + $unitJob = Start-Job -Name "UnitTests" -ScriptBlock $runUnitFunc + $jobs += $unitJob +} + +if ($livecov) +{ Write-Host -ForegroundColor DarkMagenta "[live][COV] Running Unit Tests with coverage ..." + + $env:ENVIRONMENT_NAME = "Windows (x86-64)" + coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests/unit + + Write-Host -ForegroundColor DarkMagenta "[live][COV] Convert coverage report to HTML ..." + coverage html + + Write-Host -ForegroundColor DarkMagenta "[live][COV] Convert coverage report to XML (Cobertura) ..." + coverage xml + + Write-Host -ForegroundColor DarkMagenta "[live][COV] Convert coverage report to JSON ..." + coverage json + + Write-Host -ForegroundColor DarkMagenta "[live][COV] Write coverage report to console ..." + coverage report + + if ($copycov) + { cp -Recurse -Force .\report\coverage\html\* .\doc\_build\html\coverage + Write-Host -ForegroundColor DarkMagenta "[live][COV] Copyed code coverage report to 'coverage' directory in HTML directory" + } + + Write-Host -ForegroundColor DarkMagenta "[live][COV] Coverage finished" +} +elseif ($cov) +{ Write-Host -ForegroundColor DarkMagenta "[live][COV] Running Unit Tests with coverage ..." + Write-Host -ForegroundColor DarkMagenta "[SCRIPT] Starting Coverage jobs ..." + + # Collect coverage + $collectCovFunc = { + $env:ENVIRONMENT_NAME = "Windows (x86-64)" + coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests/unit + + Write-Host -ForegroundColor DarkMagenta "[Job3][COV] Convert coverage report to HTML ..." + coverage html + + Write-Host -ForegroundColor DarkMagenta "[Job3][COV] Convert coverage report to XML (Cobertura) ..." + coverage xml + + Write-Host -ForegroundColor DarkMagenta "[Job3][COV] Convert coverage report to JSON ..." + coverage json + } + $covJob = Start-Job -Name "Coverage" -ScriptBlock $collectCovFunc + $jobs += $covJob +} + +if ($livetype) +{ Write-Host -ForegroundColor DarkCyan "[live][TYPE] Running static type analysis using mypy ..." + + $env:MYPY_FORCE_COLOR = 1 + mypy.exe -p $PackageName + + if ($copytype) + { cp -Recurse -Force .\report\typing\* .\doc\_build\html\typing + Write-Host -ForegroundColor DarkCyan "[live][TYPE] Copyed typing report to 'typing' directory in HTML directory." + } + + Write-Host -ForegroundColor DarkCyan "[live][TYPE] Static type analysis finished" +} +elseif ($type) +{ Write-Host -ForegroundColor DarkCyan "[live][TYPE] Running static type analysis using mypy ..." + Write-Host -ForegroundColor DarkCyan "[SCRIPT] Starting Typing jobs ..." + + # Analyze types + $analyzeTypesFunc = { + $env:MYPY_FORCE_COLOR = 1 + mypy.exe -p $PackageName + } + $typeJob = Start-Job -Name "Typing" -ScriptBlock $analyzeTypesFunc + $jobs += $typeJob +} + + +if ($doc) +{ Write-Host -ForegroundColor DarkGreen "[SCRIPT] Waiting on Documentation job ..." + Wait-Job -Job $docJob + Write-Host -ForegroundColor DarkYellow "[Job1][DOC] Documentation finished" +} +if ($jobs.Count -ne 0) +{ + Write-Host -ForegroundColor DarkGreen ( "[SCRIPT] Waiting on {0} jobs ({1}) ..." -f $jobs.Count, (($jobs | %{ $_.Name }) -join ", ")) + Wait-Job -Job $jobs +} + + +if (-not $liveunit -and $copyunit) +{ +# if ($unit) +# { Wait-Job -Job $unitJob +# Write-Host -ForegroundColor DarkBlue "[Job2][UNIT] Unit tests finished" +# } + cp -Recurse -Force .\report\unit\html\* .\doc\_build\html\unittests + Write-Host -ForegroundColor DarkBlue "[post][UNIT] Copyed unit testing report to 'unittests' directory in HTML directory" +} +if (-not ($livecov -or $cov) -and $copycov) +{ +# if ($cov) +# { Wait-Job -Job $unitJob +# Write-Host -ForegroundColor DarkMagenta "[Job3][UNIT] Coverage collection finished" +# } + cp -Recurse -Force .\report\coverage\html\* .\doc\_build\html\coverage + Write-Host -ForegroundColor DarkMagenta "[post][COV] Copyed code coverage report to 'coverage' directory in HTML directory" +} +if (-not $livetype -and $copytype) +{ +# if ($type) +# { Wait-Job -Job $typeJob +# Write-Host -ForegroundColor DarkCyan "[Job4][UNIT] Static type analysis finished" +# } + cp -Recurse -Force .\report\typing\* .\doc\_build\html\typing + Write-Host -ForegroundColor DarkCyan "[post][TYPE] Copyed typing report to 'typing' directory in HTML directory." +} + + +if ($type) +{ Write-Host -ForegroundColor DarkCyan "================================================================================" + if (-not $nooutput) + { Receive-Job -Job $typeJob + } + Remove-Job -Job $typeJob +} +if ($doc) +{ Write-Host -ForegroundColor DarkYellow "================================================================================" + if (-not $nooutput) + { Receive-Job -Job $docJob + } + Remove-Job -Job $docJob +} +if ($unit) +{ Write-Host -ForegroundColor DarkBlue "================================================================================" + if (-not $nooutput) + { Receive-Job -Job $unitJob + } + Remove-Job -Job $unitJob +} +if ($cov) +{ Write-Host -ForegroundColor DarkMagenta "================================================================================" + if (-not $nooutput) + { Receive-Job -Job $covJob + } + Remove-Job -Job $covJob + + if ($copycov) + { cp -Recurse -Force .\report\coverage\html\* .\doc\_build\html\coverage + Write-Host -ForegroundColor DarkMagenta "[post][COV] Copyed code coverage report to 'coverage' directory in HTML directory" + } +} +Write-Host -ForegroundColor DarkGreen "================================================================================" +Write-Host -ForegroundColor DarkGreen "[SCRIPT] Finished"