From a460326d05142a4cd461a89ada3174fa5de934f5 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 14 Nov 2024 00:39:07 +0100 Subject: [PATCH] Another setup of updates. --- .github/workflows/Pipeline.yml | 125 +-------- .gitignore | 12 +- doc/Dependency.rst | 157 ++++++++--- doc/DocCoverage.rst | 7 + doc/FurtherResources.rst | 16 +- doc/Installation.rst | 478 +++++++++++++++++++++++++++++++-- doc/TODO.rst | 4 + doc/conf.py | 195 +++++++++----- doc/coverage/index.rst | 9 +- doc/genindex.rst | 4 - doc/index.rst | 35 ++- doc/py-modindex.rst | 4 - doc/requirements.txt | 2 - doc/unittests/index.rst | 7 + lib/schema | 2 +- pyproject.toml | 2 +- setup.py | 10 +- tests/unit/requirements.txt | 1 + 18 files changed, 780 insertions(+), 290 deletions(-) create mode 100644 doc/DocCoverage.rst create mode 100644 doc/TODO.rst delete mode 100644 doc/genindex.rst delete mode 100644 doc/py-modindex.rst create mode 100644 doc/unittests/index.rst create mode 100644 tests/unit/requirements.txt diff --git a/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml index e83becd..1bce18c 100644 --- a/.github/workflows/Pipeline.yml +++ b/.github/workflows/Pipeline.yml @@ -4,124 +4,15 @@ on: push: workflow_dispatch: schedule: - - cron: '0 0 * * 5' +# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues + - cron: '0 22 * * 5' jobs: - - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev - with: - name: pyEDAA.IPXACT - - UnitTesting: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev - needs: - - Params + Pipeline: + uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r2 with: - jobs: ${{ needs.Params.outputs.python_jobs }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }} - - Coverage: - uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev - needs: - - Params - with: - python_version: ${{ needs.Params.outputs.python_version }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} + package_namespace: pyEDAA + package_name: IPXACT secrets: - codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} - - StaticTypeCheck: - uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@dev - needs: - - Params - with: - python_version: ${{ needs.Params.outputs.python_version }} - requirements: '-r tests/requirements.txt' - commands: | - cd pyEDAA - mypy --html-report ../htmlmypy -p IPXACT - html_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }} - - PublishTestResults: - uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@dev - needs: - - Coverage - - UnitTesting - - Package: - uses: pyTooling/Actions/.github/workflows/Package.yml@dev - needs: - - Params - - Coverage - with: - python_version: ${{ needs.Params.outputs.python_version }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} - - Release: - uses: pyTooling/Actions/.github/workflows/Release.yml@dev - if: startsWith(github.ref, 'refs/tags') - needs: - - UnitTesting - - Coverage - - StaticTypeCheck - - Package - - PublishOnPyPI: - uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@dev - if: startsWith(github.ref, 'refs/tags') - needs: - - Params - - Release - - Package - with: - python_version: ${{ needs.Params.outputs.python_version }} - requirements: -r dist/requirements.txt - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} - secrets: - PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} - -# VerifyDocs: -# uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@dev -# needs: -# - Params -# with: -# python_version: ${{ needs.Params.outputs.python_version }} - - BuildTheDocs: - uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@dev - needs: - - Params -# - VerifyDocs - with: - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }} - - PublishToGitHubPages: - uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@dev - needs: - - Params - - BuildTheDocs - - Coverage - - StaticTypeCheck - with: - doc: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }} - coverage: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} - typing: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }} - - ArtifactCleanUp: - uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@dev - needs: - - Params - - UnitTesting - - Coverage - - StaticTypeCheck - - BuildTheDocs - - PublishToGitHubPages - - PublishTestResults - with: - package: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} - remaining: | - ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}-* - ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} - ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }} - ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }} + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }} diff --git a/.gitignore b/.gitignore index 9cc125d..a1c036c 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,13 @@ __pycache__/ .coverage .cov coverage.xml +/report/coverage + +# mypy +/report/typing + +# pytest +/report/unit # setuptools /build/**/*.* @@ -21,5 +28,8 @@ coverage.xml /doc/pyEDAA.IPXACT/**/*.* !/doc/pyEDAA.IPXACT/index.rst -# PyCharm project +# PyCharm project files /.idea/workspace.xml + +# Git files +!.git* diff --git a/doc/Dependency.rst b/doc/Dependency.rst index 17f1e69..0accd28 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -1,48 +1,74 @@ -.. _dependency: +.. _DEP: -Dependency -########## +Dependencies +############ .. |img-IPXACT-lib-status| image:: https://img.shields.io/librariesio/release/pypi/pyEDAA.IPXACT :alt: Libraries.io status for latest release :height: 22 :target: https://libraries.io/github/edaa-org/pyEDAA.IPXACT -.. |img-IPXACT-req-status| image:: https://img.shields.io/requires/github/edaa-org/pyEDAA.IPXACT - :alt: Requires.io +.. |img-IPXACT-vul-status| image:: https://img.shields.io/snyk/vulnerabilities/github/edaa-org/pyEDAA.IPXACT + :alt: Snyk Vulnerabilities for GitHub Repo :height: 22 - :target: https://requires.io/github/edaa-org/pyEDAA.IPXACT/requirements/?branch=main + :target: https://img.shields.io/snyk/vulnerabilities/github/edaa-org/pyEDAA.IPXACT +------------------------------------------+------------------------------------------+ -| `Libraries.io `_ | `Requires.io `_ | +| `Libraries.io `_ | Vulnerabilities Summary | +==========================================+==========================================+ -| |img-IPXACT-lib-status| | |img-IPXACT-req-status| | +| |img-IPXACT-lib-status| | |img-IPXACT-vul-status| | +------------------------------------------+------------------------------------------+ +.. _DEP/package: -.. _dependency-package: +pyEDAA.IPXACT Package (Mandatory) +********************************* -pyEDAA.IPXACT Package -********************* +.. rubric:: Manually Installing Package Requirements -+---------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Package** | **Version** | **License** | **Dependencies** | -+===============================================================+=============+===========================================================================================+========================================================================================================================================================+ -| `pyTooling `__ | ≥8.0 | `Apache License, 2.0 `__ | *None* | -+---------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `lxml `__ | ≥5.3 | `BSD 3-Clause `__ | *Not yet evaluated.* | -+---------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ +Use the :file:`requirements.txt` file to install all dependencies via ``pip3`` or install the package directly from +PyPI (see :ref:`INSTALL`). -.. todo:: investigate dependencies and licenses of pyTooling with pyAttributes/argcomplete. +.. tab-set:: -.. | `pyAttributes `__ | ≥2.5.1 | `Apache License, 2.0 `__ | * `pyTooling `__ - `Apache License, 2.0 `__ | - | | | | * `argcomplete `__ - `Apache License, 2.0 `__ | - +---------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ + .. tab-item:: Linux/macOS + :sync: Linux + .. code-block:: bash -.. _dependency-testing: + pip3 install -U -r requirements.txt + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip install -U -r requirements.txt + + +.. rubric:: Dependency List + ++---------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Package** | **Version** | **License** | **Dependencies** | ++=======================================================================================+=============+==========================================================================================================+=============================================================================================================================================================+ +| `pyTooling `__ | ≥8.0 | `Apache License, 2.0 `__ | *None* | ++---------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `pyVHDLModel `__ | ≥0.29 | `Apache License, 2.0 `__ | * `pyTooling `__ (`Apache License, 2.0 `__) | ++---------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `lxml `__ | ≥5.3 | `BSD 3-Clause `__ | *Not yet evaluated.* | ++---------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. todo:: investigate dependencies and licenses of pyTooling with CLIAbstraction and pyAttributes/argcomplete. + +.. todo:: investigate dependencies of py-flags 1.1.4 => MIT. + + +.. _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. @@ -53,12 +79,23 @@ 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** | @@ -77,7 +114,8 @@ the mandatory dependencies too. +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ -.. _dependency-documentation: + +.. _DEP/documentation: Sphinx Documentation (Optional) ******************************* @@ -91,9 +129,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 @@ -105,15 +155,22 @@ the mandatory dependencies too. +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `Sphinx `__ | ≥8.1 | `BSD 3-Clause `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `sphinxcontrib-mermaid `__ | ≥1.0 | `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.2 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `sphinx_autodoc_typehints `__ | ≥2.5 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `ruamel.yaml `__ | ≥0.18 | `MIT `__ | *Not yet evaluated.* | ++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. _dependency-packaging: +.. _DEP/packaging: Packaging (Optional) ******************** @@ -127,9 +184,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 - pip3 install -U -r build/requirements.txt + .. code-block:: bash + + 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 @@ -143,7 +212,7 @@ install the mandatory dependencies too. +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -.. _dependency-publishing: +.. _DEP/publishing: Publishing (CI-Server only) *************************** @@ -158,9 +227,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/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/FurtherResources.rst b/doc/FurtherResources.rst index 8b3cb38..ab2362f 100644 --- a/doc/FurtherResources.rst +++ b/doc/FurtherResources.rst @@ -1,15 +1,15 @@ Further Resources ################# -* :pypiproject:`pyIPXACT` was moved and renamed to pyEDAA.IPXACT (this repository). -* :pypiproject:`peakrdl-ipxact` +* :pypi:`pyIPXACT` was moved and renamed to pyEDAA.IPXACT (this repository). +* :pypi:`peakrdl-ipxact` - * :pypiproject:`ralbot-ipxact` was renamed to *peakrdl-ipxact*. + * :pypi:`ralbot-ipxact` was renamed to *peakrdl-ipxact*. -* :pypiproject:`ipxact2systemverilog` -* :ghrepo:`edaa-org/IPXACT-Schema` -* :ghrepo:`iDoka/ipxact-cli-tools` -* :ghrepo:`olofk/ipyxact` -* :ghrepo:`kactus2` +* :pypi:`ipxact2systemverilog` +* :gh:`edaa-org/IPXACT-Schema` +* :gh:`iDoka/ipxact-cli-tools` +* :gh:`olofk/ipyxact` +* :gh:`kactus2` * `research.tuni.fi/system-on-chip/tool `__ diff --git a/doc/Installation.rst b/doc/Installation.rst index 35b1490..bc05e5e 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -1,56 +1,486 @@ -.. _installation: +.. |PackageName| replace:: pyEDAA.IPXACT + +.. _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 the |PackageName| package itself or the package with further dependencies for documentation +generation (``doc``), running unit tests (``test``) or just all (``all``) dependencies. + +See :ref:`DEP` for more details. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. tab-set:: + + .. tab-item:: Minimal installation + :sync: Minimal + + .. code-block:: bash + + # Basic pyEDAA.IPXACT package + pip3 install pyEDAA.IPXACT + + # Alternatively + python3 -m pip install pyEDAA.IPXACT + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: bash + + # Install with dependencies to generate documentation + pip3 install pyEDAA.IPXACT[doc] + + # Alternatively + python3 -m pip install pyEDAA.IPXACT[doc] + + .. tab-item:: With Unit Testing Dependencies + :sync: Unit + + .. code-block:: bash + + # Install with dependencies to run unit tests + pip3 install pyEDAA.IPXACT[test] + + # Alternatively + python3 -m pip install pyEDAA.IPXACT[test] + + .. tab-item:: All Developer Dependencies + :sync: All + + .. code-block:: bash + + # Install with all developer dependencies + pip3 install pyEDAA.IPXACT[all] + + # Alternatively + python3 -m pip install pyEDAA.IPXACT[all] + + .. tab-item:: Windows + :sync: Windows + + .. tab-set:: + + .. tab-item:: Minimal installation + :sync: Minimal + + .. code-block:: powershell + + # Basic pyEDAA.IPXACT package + pip install pyEDAA.IPXACT + + # Alternatively + py -m pip install pyEDAA.IPXACT + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: powershell + + # Install with dependencies to generate documentation + pip install pyEDAA.IPXACT[doc] + + # Alternatively + py -m pip install pyEDAA.IPXACT[doc] -.. _installation-pip: + .. tab-item:: With Unit Testing Dependencies + :sync: Unit -Using PIP -********* + .. code-block:: powershell -Installation from PyPI using PIP -================================ + # Install with dependencies to run unit tests + pip install pyEDAA.IPXACT[test] -.. code-block:: bash + # Alternatively + py -m pip install pyEDAA.IPXACT[test] - pip3 install pyEDAA.IPXACT + .. tab-item:: All Developer Dependencies + :sync: All + .. code-block:: powershell + + # Install with all developer dependencies + pip install pyEDAA.IPXACT[all] + + # Alternatively + py -m pip install pyEDAA.IPXACT[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 + + pyEDAA.IPXACT ~= 0.3 + + +.. _INSTALL/pip/update: Updating from PyPI using PIP ============================ -.. code-block:: bash +.. tab-set:: - pip3 install -U pyEDAA.IPXACT + .. tab-item:: Linux/macOS + :sync: Linux + .. code-block:: bash + + # Update pyEDAA.IPXACT + pip3 install -U pyEDAA.IPXACT + + # Alternatively + python3 -m pip install -U pyEDAA.IPXACT + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + # Update pyEDAA.IPXACT + pip install -U pyEDAA.IPXACT + + # Alternatively + py -m pip install -U pyEDAA.IPXACT + + +.. _INSTALL/pip/uninstall: Uninstallation using PIP ======================== -.. code-block:: bash +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash + + # Uninstall pyEDAA.IPXACT + pip3 uninstall pyEDAA.IPXACT + + # Alternatively + python3 -m pip uninstall pyEDAA.IPXACT + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + # Uninstall pyEDAA.IPXACT + pip uninstall pyEDAA.IPXACT + + # Alternatively + py -m pip uninstall pyEDAA.IPXACT + + +.. _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 pyEDAA.IPXACT + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + cd + + # Running type checking using mypy + $env:MYPY_FORCE_COLOR = 1 + mypy -p pyEDAA.IPXACT + + +.. _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. + +.. tab-set:: + + .. tab-item:: Linux/macOS + :sync: Linux + + .. code-block:: bash - pip3 uninstall pyEDAA.IPXACT + cd + # Package the code in a wheel (*.whl) + python3 -m build --wheel -Installation from local directory using PIP -=========================================== + # Uninstall the old package + python3 -m pip uninstall -y pyEDAA.IPXACT -.. code-block:: bash + # Install from wheel + python3 -m pip install ./dist/pyEDAA.IPXACT-0.3.0-py3-none-any.whl - pip3 install . + .. tab-item:: Windows + :sync: Windows + .. code-block:: powershell -.. _installation-setup: + cd -Using ``setup.py`` (legacy) -*************************** + # Package the code in a wheel (*.whl) + py -m build --wheel -See sections above on how to use PIP. + # Uninstall the old package + py -m pip uninstall -y pyEDAA.IPXACT -Installation using ``setup.py`` -=============================== + # Install from wheel + py -m pip install .\dist\pyEDAA.IPXACT-0.3.0-py3-none-any.whl -.. code-block:: bash +.. note:: - setup.py install + 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/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/conf.py b/doc/conf.py index 63df94b..2e93585 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,20 +1,27 @@ # 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 abspath to make it absolute, like shown here. - +# 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 +# ============================================================================== +# Project configuration +# ============================================================================== +githubNamespace = "edaa-org" +project = "pyEDAA.IPXACT" +directoryName = project.replace('.', '/') + +# ============================================================================== +# Project paths +# ============================================================================== ROOT = Path(__file__).resolve().parent -sys_path.insert(0, abspath('.')) -sys_path.insert(0, abspath('..')) -sys_path.insert(0, abspath('../pyEDAA/IPXACT')) -#sys_path.insert(0, abspath('_extensions')) +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) +sys_path.insert(0, abspath(f"../{directoryName}")) # ============================================================================== @@ -23,9 +30,7 @@ # 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 = "pyEDAA.IPXACT" - -packageInformationFile = Path(f"../{project.replace('.', '/')}/__init__.py") +packageInformationFile = Path(f"../{directoryName}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) author = versionInformation.Author @@ -33,27 +38,28 @@ version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. release = versionInformation.Version + # ============================================================================== # 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 +78,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 = 'pyEDAAIPXACTDoc' +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 +118,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 +150,10 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - 'pyEDAA.IPXACT.tex', - 'The pyEDAA.IPXACT Documentation', - 'Patrick Lehmann', - 'manual' + f"{project}.tex", + f"The {project} Documentation", + f"Patrick Lehmann", + f"manual" ), ] @@ -159,28 +164,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), -# 'pyFlags': ('http://pyFlags.readthedocs.io/en/latest', None), + "python": ("https://docs.python.org/3", None), + "pyTool": ("https://pyTooling.github.io/pyTooling/", None), } @@ -188,28 +197,28 @@ # 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 = { - 'ghrepo': ('https://github.com/%s', 'gh:%s'), - 'ghissue': ('https://github.com/edaa-org/pyEDAA.IPXACT/issues/%s', 'issue #%s'), - 'ghpull': ('https://github.com/edaa-org/pyEDAA.IPXACT/pull/%s', 'pull request #%s'), - 'ghsrc': ('https://github.com/edaa-org/pyEDAA.IPXACT/blob/main/%s', None), - 'pypiproject': ('https://pypi.org/project/%s', 'pypi:%s') + "gh": (f"https://GitHub.com/%s", "%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), + "pypi": ('https://PyPI.org/project/%s', '%s'), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), } @@ -219,6 +228,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 @@ -228,10 +257,46 @@ todo_link_only = True +# ============================================================================== +# sphinx-reports +# ============================================================================== +report_unittest_testsuites = { + "src": { + "name": f"{project}", + "xml_report": "../report/unit/TestReportSummary.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"../{directoryName}", + "fail_below": 80, + "levels": "default" + } +} + + +# ============================================================================== +# Sphinx_Design +# ============================================================================== +# sd_fontawesome_latex = True + # ============================================================================== # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - 'pyEDAA.IPXACT': {'output': "pyEDAA.IPXACT", "override": True} + f"{project}": { + "template": "module", + "output": project, + "override": True + } } diff --git a/doc/coverage/index.rst b/doc/coverage/index.rst index 80bbad2..bad51b9 100644 --- a/doc/coverage/index.rst +++ b/doc/coverage/index.rst @@ -1,4 +1,7 @@ -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 6ab277b..d865eb9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -78,7 +78,7 @@ IP-XACT Resources * Schema files: - * :ghrepo:`IPXACT-Schema ` at GitHub + * :gh:`IPXACT-Schema ` at GitHub * `IP-XACT `__ at `Accellera `__ .. #Comment @@ -113,7 +113,7 @@ News * Collect code coverage. -* Linked IP-XACT schema submodule to new location as :ghrepo:`edaa-org/IPXACT-Schema `. +* Linked IP-XACT schema submodule to new location as :gh:`edaa-org/IPXACT-Schema `. .. only:: html @@ -155,7 +155,7 @@ News .. rubric:: Initial Document Object Model (DOM) * Initial Document Object Model (DOM). -* Referenced IP-XACT schema definitions from :ghrepo:`UnofficialRepos/IPXACT-Schema ` +* Referenced IP-XACT schema definitions from :gh:`UnofficialRepos/IPXACT-Schema ` .. _CONTRIBUTORS: @@ -163,8 +163,8 @@ News Contributors ************ -* :ghrepo:`Patrick Lehmann ` (Maintainer) -* :ghrepo:`Unai Martinez-Corral ` +* :gh:`Patrick Lehmann ` (Maintainer) +* :gh:`Unai Martinez-Corral ` * `and more... `__ @@ -183,14 +183,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: @@ -217,13 +209,19 @@ License .. raw:: latex - \part{References} + \part{References and Reports} .. toctree:: - :caption: References + :caption: References and Reports :hidden: - pyEDAA.IPXACT/index + Python Class Reference + unittests/index + coverage/index + Doc. Coverage Report + Static Type Check Report ➚ + +.. Coverage Report ➚ .. raw:: latex @@ -233,10 +231,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 40fc7e6..0000000 --- a/doc/py-modindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. This file is a placeholder and will be replaced - -Python Module Index -################### diff --git a/doc/requirements.txt b/doc/requirements.txt index 2d35335..bfb8bf1 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -15,5 +15,3 @@ 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/lib/schema b/lib/schema index c9e00c0..60d5e03 160000 --- a/lib/schema +++ b/lib/schema @@ -1 +1 @@ -Subproject commit c9e00c091eecbe3517594856295148238fcd659b +Subproject commit 60d5e03b0abd1f62b2c024082e576d0b0a439a15 diff --git a/pyproject.toml b/pyproject.toml index f9f5bcb..4b9f1c0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [build-system] requires = [ - "setuptools ~= 75.3", + "setuptools ~= 75.5", "wheel ~= 0.45", "pyTooling ~= 8.0" ] diff --git a/setup.py b/setup.py index 3eb7c3a..ff137b5 100644 --- a/setup.py +++ b/setup.py @@ -29,6 +29,9 @@ # SPDX-License-Identifier: Apache-2.0 # # ==================================================================================================================== # # +"""Package installer for 'An abstract SystemRDL language model'.""" +from setuptools import setup + from itertools import chain from pathlib import Path from pyTooling.Packaging import DescribePythonPackageHostedOnGitHub, DEFAULT_CLASSIFIERS @@ -38,7 +41,7 @@ packageDirectory = packageName.replace(".", "/") packageInformationFile = Path(f"{packageDirectory}/__init__.py") -DescribePythonPackageHostedOnGitHub( +setup(**DescribePythonPackageHostedOnGitHub( packageName=packageName, description="A Document-Object-Model (DOM) for IP-XACT files.", gitHubNamespace=gitHubNamespace, @@ -49,11 +52,12 @@ ], dataFiles={ packageName: [ - str(file.relative_to(Path.cwd())) + str(file) for file in chain( Path.cwd().glob("ipxact*/**/*"), Path.cwd().glob("ieee*/**/*") ) ] } -) +)) + diff --git a/tests/unit/requirements.txt b/tests/unit/requirements.txt new file mode 100644 index 0000000..3c8d7e7 --- /dev/null +++ b/tests/unit/requirements.txt @@ -0,0 +1 @@ +-r ../requirements.txt