Switched documentation from BTD to vanilla Sphinx.

edaa-org · Nov 11, 2024 · 6ab3631 · 6ab3631
1 parent 4086248
commit 6ab3631
Show file tree

Hide file tree

Showing 21 changed files with 1,321 additions and 201 deletions.
diff --git 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
@@ -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 <https://libraries.io/>`_  | `Requires.io <https://requires.io/>`_    |
+| `Libraries.io <https://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 <https://GitHub.com/pytest-dev/pytest>`__                   | ≥8.3      | `MIT <https://GitHub.com/pytest-dev/pytest/blob/master/LICENSE>`__                     | *Not yet evaluated.* |
+| `pytest <https://GitHub.com/pytest-dev/pytest>`__                   | ≥8.3        | `MIT <https://GitHub.com/pytest-dev/pytest/blob/master/LICENSE>`__                     | *Not yet evaluated.* |
 +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
 | `pytest-cov <https://GitHub.com/pytest-dev/pytest-cov>`__           | ≥6.0        | `MIT <https://GitHub.com/pytest-dev/pytest-cov/blob/master/LICENSE>`__                 | *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 <https://GitHub.com/sphinx-doc/sphinx>`__                                               | ≥8.1         | `BSD 3-Clause <https://GitHub.com/sphinx-doc/sphinx/blob/master/LICENSE>`__                              | *Not yet evaluated.*                                                                                                                                 |
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `sphinxcontrib-mermaid <https://GitHub.com/mgaitan/sphinxcontrib-mermaid>`__                    | ≥0.9.2       | `BSD <https://GitHub.com/mgaitan/sphinxcontrib-mermaid/blob/master/LICENSE.rst>`__                       | *Not yet evaluated.*                                                                                                                                 |
++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `autoapi <https://GitHub.com/carlos-jenkins/autoapi>`__                                         | ≥2.0.1       | `Apache License, 2.0 <https://GitHub.com/carlos-jenkins/autoapi/blob/master/LICENSE>`__                  | *Not yet evaluated.*                                                                                                                                 |
++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `sphinx_btd_theme <https://GitHub.com/buildthedocs/sphinx.theme>`__                             | ≥0.5.2       | `MIT <https://GitHub.com/buildthedocs/sphinx.theme/blob/master/LICENSE>`__                               | *Not yet evaluated.*                                                                                                                                 |
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-| !! `sphinx_fontawesome <https://GitHub.com/fraoustin/sphinx_fontawesome>`__                     | ≥0.0.6       | `GPL 2.0 <https://GitHub.com/fraoustin/sphinx_fontawesome/blob/master/LICENSE>`__                        | *Not yet evaluated.*                                                                                                                                 |
+| `sphinx_design <https://GitHub.com/executablebooks/sphinx-design>`__                            | ≥0.6         | `MIT <https://GitHub.com/executablebooks/sphinx-design/blob/main/LICENSE>`__                             | *Not yet evaluated.*                                                                                                                                 |
++-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `sphinx-copybutton <https://GitHub.com/executablebooks/sphinx-copybutton>`__                    | ≥0.5         | `MIT <https://GitHub.com/executablebooks/sphinx-copybutton/blob/master/LICENSE>`__                       | *Not yet evaluated.*                                                                                                                                 |
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `sphinx_autodoc_typehints <https://GitHub.com/agronholm/sphinx-autodoc-typehints>`__            | ≥2.5         | `MIT <https://GitHub.com/agronholm/sphinx-autodoc-typehints/blob/master/LICENSE>`__                      | *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
@@ -1,8 +1,8 @@
 .. _DOCLICENSE:
 
-.. Note:: This is a local copy of the `Creative Commons - Attribution 4.0 International (CC BY 4.0) <https://creativecommons.org/licenses/by/4.0/legalcode>`__.
+.. note:: This is a local copy of the `Creative Commons - Attribution 4.0 International (CC BY 4.0) <https://creativecommons.org/licenses/by/4.0/legalcode>`__.
 
-.. 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
@@ -0,0 +1,7 @@
+Documentation Coverage
+######################
+
+Documentation coverage generated by `docstr-coverage <https://github.com/HunterMcGushion/docstr_coverage>`__.
+
+.. report:doc-coverage::
+   :packageid: src