Documentation fine-tuning.

2026-02-12 02:56:56 +08:00 · 2025-09-21 18:58:59 +02:00
parent fb67dd0fdb
commit b247eb4a53
28 changed files with 271 additions and 23 deletions
--- a/.github/workflows/CheckCodeQuality.yml
+++ b/.github/workflows/CheckCodeQuality.yml
@@ -35,14 +35,29 @@ on:
        default: '3.13'
        type: string
      package_directory:
-        description: '.'
+        description: 'The package''s directory'
        required: true
        type: string
      requirements:
-        description: ''
+        description: 'Python dependencies to be installed through pip.'
        required: false
        default: '-r requirements.txt'
        type: string
+      bandit:
+        description: 'Run bandit checks.'
+        required: false
+        default: 'true'
+        type: string
+      radon:
+        description: 'Run radon checks.'
+        required: false
+        default: 'true'
+        type: string
+      pylint:
+        description: 'Run pylint checks.'
+        required: false
+        default: 'true'
+        type: string
      artifact:
        description: 'Name of the package artifact.'
        required: true
@@ -52,6 +67,7 @@ jobs:
  Bandit:
    name: 🚨 Security Scanning (Bandit)
    runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}"
+    if: inputs.bandit == 'true'

    steps:
      - name: ⏬ Checkout repository
@@ -74,9 +90,18 @@ jobs:
          mkdir -p report/bandit
          bandit -c pyproject.toml -r ${{ inputs.package_directory }} -f xml -o report/bandit/report.xml

+      - name: 📊 Publish Bandit Results
+        uses: dorny/test-reporter@v2
+        continue-on-error: true
+        with:
+          name:     'Bandit Results'
+          path:     'report/bandit/report.xml'
+          reporter: java-junit
+
  Radon:
    name: ☢️ Metrics and Complexity
    runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}"
+    if: inputs.radon == 'true'

    steps:
      - name: ⏬ Checkout repository
@@ -116,6 +141,7 @@ jobs:
  PyLint:
    name: 🩺 Linting
    runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}"
+    if: inputs.pylint == 'true'

    steps:
      - name: ⏬ Checkout repository
--- a/doc/Action/Releaser.rst
+++ b/doc/Action/Releaser.rst
@@ -1,4 +1,6 @@
 .. _ACTION/Releaser:
+.. index::
+   single: GitHub Action; Releaser

 Releaser
 ########
--- a/doc/Action/With-post-step.rst
+++ b/doc/Action/With-post-step.rst
@@ -1,4 +1,6 @@
 .. _ACTION/WithPostStep:
+.. index::
+   single: GitHub Action; WithPostStep

 with-post-step
 ##############
--- a/doc/Action/index.rst
+++ b/doc/Action/index.rst
@@ -1,4 +1,6 @@
 .. _ACTION:
+.. index::
+   single: GitHub Action

 Overview
 ########
@@ -9,6 +11,8 @@ The following 2 actions are provided by **Actions**:


 .. _ACTION/Instantiation:
+.. index::
+   single: GitHub Action; Instantiation

 Instantiation
 *************
--- a/doc/Glossary.rst
+++ b/doc/Glossary.rst
@@ -0,0 +1,128 @@
+Glossary
+########
+
+.. glossary::
+
+   Bandit
+     Bandit is a tool designed to find common security issues in Python code.
+
+     :Source Code:   `https://github.com/PyCQA/bandit/`__
+     :Package:       `https://pypi.org/project/bandit/`__
+     :Documentation: `https://bandit.readthedocs.io/`__
+
+   build
+     A simple, correct Python build frontend.
+
+     :Source Code:   `https://github.com/pypa/build/`__
+     :Package:       `https://pypi.org/project/build/`__
+     :Documentation: `https://build.pypa.io/`__
+
+   Codacy
+     .. todo:: Add description of Codacy.
+
+     :Service:       `Codacy.com <https://www.codacy.com/>`__
+
+   CodeCov
+     .. todo:: Add description of CodeCov.
+
+     :Service:       `Codecov.io <https://about.codecov.io/>`__
+
+   Coverage.py
+     The code coverage tool for Python.
+
+     :Source Code:   `https://github.com/nedbat/coveragepy/`__
+     :Package:       `https://pypi.org/project/coverage/`__
+     :Documentation: `https://coverage.readthedocs.io/`__
+
+   delete-artifact
+     A GitHub Action to deletes artifacts within the workflow run.
+
+     :Source Code:   `https://github.com/GeekyEggo/delete-artifact/`__
+     :Marketplace:   `https://github.com/marketplace/actions/delete-artifact/`__
+     :README:        `https://github.com/GeekyEggo/delete-artifact/blob/main/README.md`__
+
+   docstr_coverage
+     Docstring coverage analysis and rating for Python.
+
+     :Source Code:   `https://github.com/HunterMcGushion/docstr_coverage/`__
+     :Package:       `https://pypi.org/project/docstr_coverage/`__
+     :Documentation: `https://docstr-coverage.readthedocs.io/`__
+
+   gh
+     GitHub’s official command line tool.
+
+     :Source Code:   `https://github.com/cli/cli/`__
+     :Documentation: `https://cli.github.com/manual/`__
+
+   GitHub Pages
+     GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository
+     on GitHub, optionally runs the files through a build process, and publishes a website.
+
+     :Documentation: https://docs.github.com/en/pages
+
+   interrogate
+     Explain yourself! Interrogate a codebase for docstring coverage.
+
+     :Source Code:   `https://github.com/econchick/interrogate/`__
+     :Package:       `https://pypi.org/project/interrogate/`__
+     :Documentation: `https://interrogate.readthedocs.io/`__
+
+   MikTeX
+     MiKTeX is a modern TeX distribution for Windows, Linux and macOS.
+
+     :Source Code:   `https://github.com/MiKTeX/miktex/`__
+     :Documentation: `https://miktex.org/`__
+
+   mypy
+     Optional static typing for Python.
+
+     :Source Code:   `https://github.com/python/mypy/`__
+     :Package:       `https://pypi.org/project/mypy/`__
+     :Documentation: `https://www.mypy-lang.org/`__
+
+   pyEDAA.Reports
+     A collection of various (EDA tool-specific) report data formats.
+
+     :Source Code:   `https://github.com/edaa-org/pyEDAA.Reports/`__
+     :Package:       `https://pypi.org/project/pyEDAA.Reports/`__
+     :Documentation: `https://edaa-org.github.io/pyEDAA.Reports/`__
+
+   pip
+     The Python package installer.
+
+     :Source Code:   `https://github.com/pypa/pip/`__
+     :Package:       `https://pypi.org/project/pip/`__
+     :Documentation: `https://pip.pypa.io/`__
+
+   PyPI
+     Find, install and publish Python packages with the Python Package Index.
+
+     :URL:           `PyPI.org <https://pypi.org/>`__
+
+   pytest
+     The pytest framework makes it easy to write small tests, yet scales to support complex functional testing.
+
+     :Source Code:   `https://github.com/pytest-dev/pytest/`__
+     :Package:       `https://pypi.org/project/pytest/`__
+     :Documentation: `https://pytest.org/`__
+
+   Sphinx
+     The Sphinx documentation generator.
+
+     :Source Code:   `https://github.com/sphinx-doc/sphinx/`__
+     :Package:       `https://pypi.org/project/sphinx/`__
+     :Documentation: `https://www.sphinx-doc.org/`__
+
+   Test Reporter
+     Displays test results from popular testing frameworks directly in GitHub.
+
+     :Source Code:   `https://github.com/dorny/test-reporter/`__
+     :Marketplace:   `https://github.com/marketplace/actions/test-reporter/`__
+     :README:        `https://github.com/dorny/test-reporter/blob/main/README.md`__
+
+   twine
+     Utilities for interacting with PyPI.
+
+     :Source Code:   `https://github.com/pypa/twine/`__
+     :Package:       `https://pypi.org/project/twine/`__
+     :Documentation: `https://twine.readthedocs.io/`__
--- a/doc/JobTemplate/AllInOne/CompletePipeline.rst
+++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst
@@ -1,4 +1,22 @@
 .. _JOBTMPL/CompletePipeline:
+.. index::
+   single: build; CompletePipeline Template
+   single: Bandit; CompletePipeline Template
+   single: CodeCov; CompletePipeline Template
+   single: Codacy; CompletePipeline Template
+   single: Coverage.py; CompletePipeline Template
+   single: docstr_coverage; CompletePipeline Template
+   single: GitHub Pages; CompletePipeline Template
+   single: interrogate; CompletePipeline Template
+   single: MikTeX; CompletePipeline Template
+   single: mypy; CompletePipeline Template
+   single: PyPI; CompletePipeline Template
+   single: pytest; CompletePipeline Template
+   single: pyEDAA.Reports; CompletePipeline Template
+   single: Sphinx; CompletePipeline Template
+   single: Test Reporter; CompletePipeline Template
+   single: twine; CompletePipeline Template
+   single: GitHub Action Reusable Workflow; CompletePipeline Template

 CompletePipeline
 ################
@@ -16,56 +34,57 @@ It can be used for simple Python packages as well as namespace packages.

         .. rubric:: Testing

-         * Run unit tests.
-         * Run platform tests.
-         * Run application tests on target platform.
+         * Run unit tests before packaging using :term:`pytest`.
+         * Run platform tests before packaging using :term:`pytest`.
+         * Run application tests using packaged code on target platform.

         .. rubric:: Code Quality

-         * Collect code coverage.
-         * Check documentation coverage.
-         * Check static typing closure.
+         * Collect code coverage using :term:`Coverage.py`.
+         * Check documentation coverage using :term:`docstr_coverage` and :term:`interrogate`.
+         * Check static typing closure using :term:`mypy`.
+         * Static Application Security Testing (SAST) using :term:`bandit`

         .. rubric:: Report Handling

-         * Merge unit test results into a single summary report.
-         * Merge code coverage results into a single summary report.
+         * Merge unit test results into one report using :term:`pyEDAA.Reports`.
+         * Merge code coverage results into one report using :term:`Coverage.py`.

      .. grid-item::
         :columns: 4

         .. rubric:: Documentation

-         * Compile documentation using Sphinx as HTML and LaTeX.
-         * Translate LaTeX documentation to PDF.
+         * Compile documentation using :term:`Sphinx` as HTML and LaTeX.
+         * Translate LaTeX documentation to PDF using :term:`MikTeX`.

         .. rubric:: Publishing Results

         * GitHub Pipeline Summary

-           * Publish unittest results using :gh:`dorny/test-reporter`.
+           * Publish unittest results using :term:`Test Reporter`.

-         * GitHub Pages
+         * :term:`GitHub Pages`

           * Publish HTML documentation to GitHub Pages.

-         * Codacy
-
-           * Publish code coverage to Codacy.
-
-         * CodeCov
+         * :term:`Codecov`

           * Publish code coverage to CodeCov.
           * Publish unittest results to CodeCov.

+         * :term:`Codacy`
+
+           * Publish code coverage to Codacy.
+
      .. grid-item::
         :columns: 4

         .. rubric:: Packaging

-         * Package as wheel.
-         * Install wheel on target platform.
-         * Upload to PyPI.
+         * Package as wheel using :term:`build`.
+         * Install wheel on target platform using pip.
+         * Upload to PyPI using :term:`twine`.

         .. rubric:: Releasing

--- a/doc/JobTemplate/AllInOne/index.rst
+++ b/doc/JobTemplate/AllInOne/index.rst
@@ -14,7 +14,7 @@ Such a all-in-one workflow template covers:
 * pulishing of unit test and code coverage results
 * merging of test reports
 * packaging as wheel
-* publishing wheels tp PyPI
+* publishing wheels to PyPI
 * documentation generation via Sphinx and Miktex
 * automatic tagging of release commits
 * releasing
--- a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst
+++ b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/ArtifactCleanup:
+.. index::
+   single: delete-artifact; ArtifactCleanUp Template
+   single: GitHub Action Reusable Workflow; ArtifactCleanUp Template

 ArtifactCleanUp
 ###############
--- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst
+++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/IntermediateCleanUp:
+.. index::
+   single: delete-artifact; IntermediateCleanUp Template
+   single: GitHub Action Reusable Workflow; IntermediateCleanUp Template

 IntermediateCleanUp
 ###################
--- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst
+++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/LaTeXDocumentation:
+.. index::
+   single: MikTeX; LaTeXDocumentation Template
+   single: GitHub Action Reusable Workflow; LaTeXDocumentation Template

 LaTeXDocumentation
 ##################
--- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst
+++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/PublishToGitHubPages:
+.. index::
+   single: GitHub Pages; PublishToGitHubPages Template
+   single: GitHub Action Reusable Workflow; PublishToGitHubPages Template

 PublishToGitHubPages
 ####################
--- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst
+++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/SphinxDocumentation:
+.. index::
+   single: Sphinx; SphinxDocumentation Template
+   single: GitHub Action Reusable Workflow; SphinxDocumentation Template

 SphinxDocumentation
 ###################
--- a/doc/JobTemplate/Package/InstallPackage.rst
+++ b/doc/JobTemplate/Package/InstallPackage.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/InstallPackage:
+.. index::
+   single: pip; InstallPackage Template
+   single: GitHub Action Reusable Workflow; InstallPackage Template

 InstallPackage (beta)
 #####################
--- a/doc/JobTemplate/Package/Package.rst
+++ b/doc/JobTemplate/Package/Package.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/Package:
+.. index::
+   single: build; Package Template
+   single: GitHub Action Reusable Workflow; Package Template

 Package
 #######
--- a/doc/JobTemplate/Package/PublishOnPyPI.rst
+++ b/doc/JobTemplate/Package/PublishOnPyPI.rst
@@ -1,4 +1,8 @@
 .. _JOBTMPL/PublishOnPyPI:
+.. index::
+   single: PyPI; PublishOnPyPI Template
+   single: twine; PublishOnPyPI Template
+   single: GitHub Action Reusable Workflow; PublishOnPyPI Template

 PublishOnPyPI
 #############
--- a/doc/JobTemplate/Publish/PublishCoverageResults.rst
+++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst
@@ -1,4 +1,9 @@
 .. _JOBTMPL/PublishCoverageResults:
+.. index::
+   single: CodeCov; PublishCoverageResults Template
+   single: Codacy; PublishCoverageResults Template
+   single: Coverage.py; PublishCoverageResults Template
+   single: GitHub Action Reusable Workflow; PublishCoverageResults Template

 PublishCoverageResults
 ######################
--- a/doc/JobTemplate/Publish/PublishTestResults.rst
+++ b/doc/JobTemplate/Publish/PublishTestResults.rst
@@ -1,4 +1,9 @@
 .. _JOBTMPL/PublishTestResults:
+.. index::
+   single: CodeCov; PublishTestResults Template
+   single: pyEDAA.Reports; PublishTestResults Template
+   single: Test Reporter; PublishTestResults Template
+   single: GitHub Action Reusable Workflow; PublishTestResults Template

 PublishTestResults
 ##################
--- a/doc/JobTemplate/Quality/CheckDocumentation.rst
+++ b/doc/JobTemplate/Quality/CheckDocumentation.rst
@@ -1,4 +1,8 @@
 .. _JOBTMPL/CheckDocumentation:
+.. index::
+   single: docstr_coverage; CheckDocumentation Template
+   single: interrogate; CheckDocumentation Template
+   single: GitHub Action Reusable Workflow; CheckDocumentation Template

 CheckDocumentation
 ##################
--- a/doc/JobTemplate/Quality/StaticTypeCheck.rst
+++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/StaticTypeCheck:
+.. index::
+   single: mypy; StaticTypeCheck Template
+   single: GitHub Action Reusable Workflow; StaticTypeCheck Template

 StaticTypeCheck
 ###############
--- a/doc/JobTemplate/Release/PublishReleaseNotes.rst
+++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/PublishReleaseNotes:
+.. index::
+   single: gh; PublishReleaseNotes Template
+   single: GitHub Action Reusable Workflow; PublishReleaseNotes Template

 PublishReleaseNotes
 ###################
--- a/doc/JobTemplate/Release/TagReleaseCommit.rst
+++ b/doc/JobTemplate/Release/TagReleaseCommit.rst
@@ -1,4 +1,7 @@
 .. _JOBTMPL/TagReleaseCommit:
+.. index::
+   single: gh; TagReleaseCommit Template
+   single: GitHub Action Reusable Workflow; TagReleaseCommit Template

 TagReleaseCommit
 ################
--- a/doc/JobTemplate/Setup/ExtractConfiguration.rst
+++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst
@@ -1,4 +1,6 @@
 .. _JOBTMPL/ExtractConfiguration:
+.. index::
+   single: GitHub Action Reusable Workflow; ExtractConfiguration Template

 ExtractConfiguration
 ####################
--- a/doc/JobTemplate/Setup/Parameters.rst
+++ b/doc/JobTemplate/Setup/Parameters.rst
@@ -1,4 +1,6 @@
 .. _JOBTMPL/Parameters:
+.. index::
+   single: GitHub Action Reusable Workflow; Parameters Template

 Parameters
 ##########
--- a/doc/JobTemplate/Setup/PrepareJob.rst
+++ b/doc/JobTemplate/Setup/PrepareJob.rst
@@ -1,4 +1,6 @@
 .. _JOBTMPL/PrepareJob:
+.. index::
+   single: GitHub Action Reusable Workflow; PrepareJob Template

 PrepareJob
 ##########
--- a/doc/JobTemplate/Testing/UnitTesting.rst
+++ b/doc/JobTemplate/Testing/UnitTesting.rst
@@ -1,4 +1,8 @@
 .. _JOBTMPL/UnitTesting:
+.. index::
+   single: pytest; UnitTesting Template
+   single: Coverage.py; UnitTesting Template
+   single: GitHub Action Reusable Workflow; UnitTesting Template

 UnitTesting
 ###########
--- a/doc/JobTemplate/index.rst
+++ b/doc/JobTemplate/index.rst
@@ -1,4 +1,6 @@
 .. _JOBTMPL:
+.. index::
+   single: GitHub Action Reusable Workflow

 Overview
 ########
@@ -11,6 +13,8 @@ customizable.


 .. _JOBTMPL/Instantiation:
+.. index::
+   single: GitHub Action Reusable Workflow; Instantiation

 Instantiation
 *************
@@ -56,6 +60,8 @@ Some templates might provide output parameters, which can be used in dependent j


 .. _JOBTMPL/CommonParameters:
+.. index::
+   single: GitHub Action Reusable Workflow; Common Parameters

 Common Parameters
 *****************
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -220,6 +220,7 @@ extlinks = {
 	"ghsrc":     (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None),
 	"wiki":      (f"https://en.wikipedia.org/wiki/%s", None),
 	"pypi":      (f"https://pypi.org/project/%s/", "PyPI: %s"),
+	"rtd":       (f"https://%s.readthedocs.io/", "RTD: %s"),
 	"ucrt64":    (f"https://packages.msys2.org/packages/mingw-w64-ucrt-x86_64-%s", "UCRT64: %s"),
 	"dockerhub": (f"https://hub.docker.com/r/%s", "Docker Hub: %s"),
 }
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -317,4 +317,6 @@ License

   License
   Doc-License
+   Glossary
+   genindex
   TODO