diff --git a/doc/CodeCoverage.rst b/doc/CodeCoverage.rst index 217fd1e4..e812a534 100644 --- a/doc/CodeCoverage.rst +++ b/doc/CodeCoverage.rst @@ -22,4 +22,4 @@ Code Coverage Report Code coverage report generated with `pytest `__, `Coverage.py `__ and visualized by -`sphinx-reports `__. +`pyTooling.Sphinx `__. diff --git a/doc/DocCoverage.rst b/doc/DocCoverage.rst index d2ee3882..1f457410 100644 --- a/doc/DocCoverage.rst +++ b/doc/DocCoverage.rst @@ -21,4 +21,4 @@ Documentation Coverage Report ---------- Documentation coverage generated with `"""docstr-coverage""" `__ and -visualized by `sphinx-reports `__. +visualized by `pyTooling.Sphinx `__. diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index b30520d5..f897a9be 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -110,6 +110,126 @@ It can be used for simple Python packages as well as namespace packages. .. image:: ../../_static/pyTooling-Actions-SimplePackage.png +.. topic:: Workflow Hierarchy + + The jobs of :file:`CompletePipeline.yml` in job order, each with the reusable workflow it calls, and the actions + that workflow uses: 📄 a workflow, 🧩 a composite action with the actions it uses, 🔗 a third-party action, 🐳 a + container image. + + .. tree:: + :root-icon: 📄 + :node-icon: 📄 + :leaf-icon: 📄 + :icons: + 🧩, > 🔗, = 🐳 + :expanded-levels: 1 + + - :file:`CompletePipeline.yml` + - :ref:`PrepareJob.yml ` | job ``Prepare`` + > :gh:`actions/checkout@v7 ` + - :ref:`ExtractConfiguration.yml ` | job ``ConfigParams`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`Parameters.yml ` | job ``UnitTestingParams`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`Parameters.yml ` | job ``AppTestingParams`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`Parameters.yml ` | job ``InstallParams`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`CheckReleaseVersion.yml ` | job ``VersionCheck`` + > :gh:`actions/setup-python@v7 ` + - :ref:`UnitTesting.yml ` | job ``UnitTesting`` + > :gh:`actions/checkout@v7 ` + + :ghsrc:`ComputeRequirements <.github/actions/ComputeRequirements>` | Compute paths to requirements files + + :ghsrc:`ComputePacboyPackages <.github/actions/ComputePacboyPackages>` | Compute pacman/pacboy packages + > :gh:`msys2/setup-msys2@v2 ` + > :gh:`actions/setup-python@v7 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`StaticTypeCheck.yml ` | job ``StaticTypeCheck`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + + :ghsrc:`ComputeRequirements <.github/actions/ComputeRequirements>` | Compute paths to requirements files + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`CheckCodeQuality.yml ` | job ``CodeQuality`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + > :gh:`dorny/test-reporter@v3 ` + - :ref:`CheckDocumentation.yml ` | job ``DocCoverage`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`Package.yml ` | job ``Package`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`InstallPackage.yml ` | job ``Install`` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + > :gh:`msys2/setup-msys2@v2 ` + > :gh:`actions/setup-python@v7 ` + - :ref:`ApplicationTesting.yml ` | job ``AppTesting`` + > :gh:`actions/checkout@v7 ` + + :ghsrc:`ComputeRequirements <.github/actions/ComputeRequirements>` | Compute paths to requirements files + + :ghsrc:`ComputePacboyPackages <.github/actions/ComputePacboyPackages>` | Compute pacman/pacboy packages + > :gh:`msys2/setup-msys2@v2 ` + > :gh:`actions/setup-python@v7 ` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`PublishCoverageResults.yml ` | job ``PublishCoverageResults`` + > :gh:`actions/checkout@v7 ` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + > :gh:`codecov/codecov-action@v7 ` + > :gh:`codacy/codacy-coverage-reporter-action@v1 ` + - :ref:`PublishTestResults.yml ` | job ``PublishTestResults`` + > :gh:`actions/checkout@v7 ` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + > :gh:`dorny/test-reporter@v3 ` + > :gh:`codecov/codecov-action@v7 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`SphinxDocumentation.yml ` | job ``Documentation`` + > :gh:`actions/checkout@v7 ` + > :gh:`actions/setup-python@v7 ` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`CleanupArtifacts.yml ` | job ``IntermediateCleanUp`` + > :gh:`geekyeggo/delete-artifact@v6 ` + - :ref:`LaTeXDocumentation.yml ` | job ``PDFDocumentation`` + = :dockerhub:`pytooling/miktex:sphinx ` | container image + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + + :gh:`pyTooling/upload-artifact@v7 ` + > :gh:`actions/upload-artifact@v7 ` + - :ref:`PublishToGitHubPages.yml ` | job ``PublishToGitHubPages`` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + > :gh:`geekyeggo/delete-artifact@v6 ` + > :gh:`actions/upload-pages-artifact@v5 ` + > :gh:`actions/deploy-pages@v5 ` + - :ref:`TagReleaseCommit.yml ` | job ``TriggerTaggedRelease`` + > :gh:`actions/github-script@v9 ` + - :ref:`PublishReleaseNotes.yml ` | job ``ReleasePage`` + > :gh:`actions/checkout@v7 ` + - :ref:`PublishOnPyPI.yml ` | job ``PublishOnPyPI`` + + :gh:`pyTooling/download-artifact@v8 ` + > :gh:`actions/download-artifact@v8 ` + > :gh:`actions/setup-python@v7 ` + > :gh:`geekyeggo/delete-artifact@v6 ` + - :ref:`CleanupArtifacts.yml ` | job ``ArtifactCleanUp`` + > :gh:`geekyeggo/delete-artifact@v6 ` + .. topic:: Dependencies .. dropdown:: Expand List @@ -386,31 +506,38 @@ version ``@r8``. It only requires the `package_name` parameter to run a full pip .. tab-item:: Simple Package :sync: Simple - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + - :file:`ProjectRoot/` + - :file:`myFramework/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. tab-item:: Namespace Package :sync: Namespace - .. code-block:: + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 - 📂ProjectRoot/ - 📂myFramework/ - 📂Extension/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + - :file:`ProjectRoot/` + - :file:`myFramework/` + - :file:`Extension/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. _JOBTMPL/CompletePipeline/Parameters: @@ -549,16 +676,20 @@ package_namespace .. rubric:: Example Directory Structure - .. code-block:: + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 - 📂ProjectRoot/ - 📂myFramework/ - 📂Extension/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + - :file:`ProjectRoot/` + - :file:`myFramework/` + - :file:`Extension/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. _JOBTMPL/CompletePipeline/Input/package_name: @@ -596,15 +727,19 @@ package_name .. rubric:: Example Directory Structure - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 + + - :file:`ProjectRoot/` + - :file:`myFramework/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. _JOBTMPL/CompletePipeline/Input/version_file: diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 59ce43e1..95a5962c 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -310,16 +310,20 @@ package_namespace .. rubric:: Example Directory Structure - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ - 📂Extension/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 + + - :file:`ProjectRoot/` + - :file:`myFramework/` + - :file:`Extension/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. _JOBTMPL/Parameters/Input/package_name: @@ -358,15 +362,19 @@ package_name .. rubric:: Example Directory Structure - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: * 📦 + + - :file:`ProjectRoot/` + - :file:`myFramework/` + * :file:`SubPackage/` + - :file:`__init__.py` + - :file:`SubModuleA.py` + - :file:`__init__.py` + - :file:`ModuleB.py` .. _JOBTMPL/Parameters/Input/python_version: diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index ec147691..1a1f8b60 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -472,15 +472,19 @@ ucrt64_before_script .. card:: Directory Structure - .. code-block:: - - / - doc/ - myPackage/ - __init__.py - tests/ - unit/ - myTests.py + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 🐍 + :icons: > 📂 + + - :file:`/` + > :file:`doc/` + - :file:`myPackage/` + - :file:`__init__.py` + - :file:`tests/` + - :file:`unit/` + - :file:`myTests.py` .. grid-item:: :columns: 3 diff --git a/doc/RepositoryStructure.rst b/doc/RepositoryStructure.rst index 29a9212d..de79f639 100644 --- a/doc/RepositoryStructure.rst +++ b/doc/RepositoryStructure.rst @@ -30,32 +30,36 @@ structure. * Packages are build with ``build`` instead of ``setuptools``. * A repository overview is given in a ``README.md``. -.. code-block:: - - / - .github/ - workflows/ - Pipeline.yml - dependabot.yml - .vscode/ - settings.json - build/ - requirements.txt - dist/ - requirements.txt - doc/ - conf.py - index.rst - requirements.txt - - __init__.py - tests/ - unit/ - requirements.txt - .editorconfig - .gitignore - LICENSE.md - pyproject.toml - README.md - requirements.txt - setup.py +.. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 📄 + :icons: > 📂, + 🐍 + + - :file:`/` + - :file:`.github/` + - :file:`workflows/` + - :file:`Pipeline.yml` + - :file:`dependabot.yml` + - :file:`.vscode/` + - :file:`settings.json` + - :file:`build/` + - :file:`requirements.txt` + - :file:`dist/` + - :file:`requirements.txt` + - :file:`doc/` + + :file:`conf.py` + - :file:`index.rst` + - :file:`requirements.txt` + - :file:`/` + + :file:`__init__.py` + - :file:`tests/` + > :file:`unit/` + - :file:`requirements.txt` + - :file:`.editorconfig` + - :file:`.gitignore` + - :file:`LICENSE.md` + - :file:`pyproject.toml` + - :file:`README.md` + - :file:`requirements.txt` + + :file:`setup.py` diff --git a/doc/conf.py b/doc/conf.py index 1c58d55b..7376ace8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -142,8 +142,10 @@ "fontpkg": dedent("""\ \\usepackage[fontfamily=libertinus]{pytooling} """), + # A 'tree' is a nested bullet list in LaTeX, which allows 4 levels unless 'maxlistdepth' is set. "passoptionstopackages": dedent("""\ \\PassOptionsToPackage{verbatimvisiblespace=\\ }{sphinx} + \\PassOptionsToPackage{maxlistdepth=10}{sphinx} """), # "sphinxsetup": "verbatimvisiblespace=\\textvisiblespace" # "figure_align": "htbp", # Latex figure (float) alignment @@ -185,7 +187,8 @@ "sphinx_copybutton", "sphinx_autodoc_typehints", "autoapi.sphinx", - "sphinx_reports", +# pyTooling extensions + "pyTooling.Sphinx", # User defined extensions ] @@ -269,15 +272,15 @@ # ============================================================================== -# sphinx-reports +# pyTooling.Sphinx - reports of domain 'report' # ============================================================================== -report_unittest_testsuites = { +pyTooling_Unittest_Testsuites = { "src": { "name": f"{pythonProject}", "xml_report": "../report/unit/unittest.xml", } } -report_codecov_packages = { +pyTooling_CodeCoverage_Packages = { "src": { "name": f"{pythonProject}", "json_report": "../report/coverage/coverage.json", @@ -285,7 +288,7 @@ "levels": "default" } } -report_doccov_packages = { +pyTooling_DocCoverage_Packages = { "src": { "name": f"{pythonProject}", "directory": f"../{directoryName}", diff --git a/doc/index.rst b/doc/index.rst index 81fed656..53075ceb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -78,34 +78,38 @@ Example Pipelines .. tab-item:: Directory Structure - .. code-block:: - - / - .github/ - workflows/ - Pipeline.yml - dist/ - requirements.txt - docs/ - conf.py - index.rst - requirements.txt - myPackage/ - ModuleA.py - __init__.py - py.typed - tests/ - unit/ - TestA.py - requirements.txt - requirements.txt - .editorconfig - .gitignore - LICENSE.md - pyproject.toml - README.md - requirements.txt - setup.py + .. tree:: + :root-icon: 📂 + :node-icon: 📂 + :leaf-icon: 📄 + :icons: + 🐍 + + - :file:`/` + - :file:`.github/` + - :file:`workflows/` + - :file:`Pipeline.yml` + - :file:`dist/` + - :file:`requirements.txt` + - :file:`doc/` + + :file:`conf.py` + - :file:`index.rst` + - :file:`requirements.txt` + - :file:`myPackage/` + + :file:`ModuleA.py` + + :file:`__init__.py` + - :file:`py.typed` + - :file:`tests/` + - :file:`unit/` + + :file:`TestA.py` + - :file:`requirements.txt` + - :file:`requirements.txt` + - :file:`.editorconfig` + - :file:`.gitignore` + - :file:`LICENSE.md` + - :file:`pyproject.toml` + - :file:`README.md` + - :file:`requirements.txt` + + :file:`setup.py` .. tab-item:: Simple Package :selected: diff --git a/doc/prolog.inc b/doc/prolog.inc index 79ce733f..4a75b885 100644 --- a/doc/prolog.inc +++ b/doc/prolog.inc @@ -4,64 +4,14 @@ .. include:: .. include:: -.. # define a hard line break for HTML -.. |br| raw:: html - -
- -.. # define horizontal line for HTML -.. |hr| raw:: html - -
- -.. # define additional CSS based styles and ReST roles for HTML -.. raw:: html - - - -.. role:: bolditalic - :class: bolditalic - -.. role:: underline - :class: underline - -.. role:: strike - :class: strike - -.. role:: xlarge - :class: xlarge - -.. role:: red - :class: colorred -.. role:: green - :class: colorgreen -.. role:: blue - :class: colorblue -.. role:: purple - :class: colorpurple - -.. role:: deletion - :class: colorred strike -.. role:: addition - :class: colorgreen +.. # |degree|, |br| and |hr|, the style roles and :pycode: are registered by the + # 'pyTooling.Sphinx' extension, so they are declared once for every project instead of being + # copied into each one's prolog. .. role:: bashcode(code) :language: bash :class: highlight -.. role:: pycode(code) - :language: python - :class: highlight - .. role:: jsoncode(code) :language: json :class: highlight diff --git a/doc/requirements.txt b/doc/requirements.txt index feca078d..25e73c28 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,7 @@ --r ../requirements.txt - -pyTooling ~= 8.17 +# The documentation's Sphinx extension - roles, 'tree', 'shields', ... Its extra 'reports' adds the domain 'report' +# (unit tests, code and documentation coverage). It requires pyTooling 10 from GitHub, which conflicts with +# 'pyTooling ~= 8.17' in '../requirements.txt', so that file isn't included here. +pyTooling.Sphinx[reports] @ git+https://github.com/pyTooling/pyTooling.Sphinx.git@dev # Enforce latest version on ReadTheDocs sphinx ~= 9.1 @@ -16,4 +17,3 @@ autoapi >= 2.0.1 sphinx_design ~= 0.7.0 sphinx-copybutton >= 0.5.2 sphinx_autodoc_typehints ~= 3.13 -sphinx_reports ~= 0.11.0