diff --git a/.github/dependabot.yml b/.github/dependabot.yml index cd81235b..f852552b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -10,3 +10,16 @@ updates: - Dependencies schedule: interval: "daily" # Checks on Monday trough Friday. + + # Maintain GitHub Action runners + - package-ecosystem: "github-actions" + directory: "/" + target-branch: dev + commit-message: + prefix: "[Dependabot]" + labels: + - Dependencies + assignees: + - Paebbels + schedule: + interval: "daily" # Checks on Monday trough Friday. diff --git a/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml index a4c71782..0d11beae 100644 --- a/.github/workflows/Pipeline.yml +++ b/.github/workflows/Pipeline.yml @@ -7,18 +7,25 @@ on: # Every Friday at 22:00 - rerun pipeline to check for dependency-based issues - cron: '0 22 * * 5' +permissions: + actions: write + contents: write + pages: write + id-token: write + jobs: Pipeline: uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r7 with: package_name: 'sphinx_reports' - unittest_python_version_list: '3.11 3.12 3.13 3.14' + unittest_python_version_list: '3.12 3.13 3.14' # dropped 3.11 due to Sphinx 9.1 dropping 3.11 unittest_disable_list: 'windows-arm:* windows-arm:pypy-3.11' bandit: 'true' pylint: 'false' codecov: 'true' codacy: 'true' dorny: 'true' + documentation_steps: 'html latex pdf pages' secrets: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/README.md b/README.md index dbcc72ad..f175bf14 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Sourcecode on GitHub](https://img.shields.io/badge/pyTooling-sphinx--reports-323131.svg?logo=github&longCache=true)](https://github.com/pyTooling/sphinx-reports) [![Sourcecode License](https://img.shields.io/pypi/l/sphinx-reports?longCache=true&style=flat-square&logo=Apache&label=code)](LICENSE.md) [![Documentation](https://img.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2Fsphinx-reports&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2Fsphinx%2Dreports%2Findex.html)](https://pyTooling.github.io/sphinx-reports/) -[![Documentation License](https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff)](LICENSE.md) +[![Documentation License](https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff)](doc/Doc-License.rst) [![PyPI](https://img.shields.io/pypi/v/sphinx-reports?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072)](https://pypi.org/project/sphinx-reports/) ![PyPI - Status](https://img.shields.io/pypi/status/sphinx-reports?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-reports?longCache=true&style=flat-square&logo=PyPI&logoColor=FBE072) diff --git a/dist/requirements.txt b/dist/requirements.txt index e87980bd..fc810d11 100644 --- a/dist/requirements.txt +++ b/dist/requirements.txt @@ -1,2 +1,2 @@ -wheel ~= 0.45.0 +wheel ~= 0.46.3 twine ~= 6.2 diff --git a/doc/CodeCov/index.rst b/doc/CodeCov/index.rst index ca4845a6..05d48385 100644 --- a/doc/CodeCov/index.rst +++ b/doc/CodeCov/index.rst @@ -1,4 +1,4 @@ -.. _CODECOV: +.. _CODECOVER: Code Coverage ############# @@ -10,7 +10,7 @@ Code Coverage The :rst:dir:`report:code-coverage` directive generates a code coverage report summary table. The code coverage report file(s) need to be configured in Sphinx's ``conf.py`` for pre-analysis and data aggregation - (:ref:`see below ` for details). This also allows the directive to supports multiple code coverage + (:ref:`see below ` for details). This also allows the directive to supports multiple code coverage reports per Sphinx documentation. Each code coverage report is referenced by the :rst:dir:`reportid ` option, which matches the dictionary key used in the configuration file. @@ -62,7 +62,7 @@ Code Coverage .. image:: ../_static/CodeCoverage.png -.. _CODECOV/Config: +.. _CODECOVER/Config: Configuration Entries in :file:`conf.py` **************************************** @@ -134,7 +134,7 @@ Configuration Entries in :file:`conf.py` } -.. _CODECOV/Example: +.. _CODECOVER/Example: Example Document **************** @@ -197,7 +197,7 @@ The second file shows how to integrate that document into the navigation bar / * :hidden: -.. _CODECOV/Directives: +.. _CODECOVER/Directives: Sphinx Directives ***************** @@ -249,7 +249,7 @@ The following directives are provided for visualizing code coverage reports. -.. _CODECOV/Roles: +.. _CODECOVER/Roles: Sphinx Roles ************ @@ -257,7 +257,7 @@ Sphinx Roles *There are no roles defined.* -.. _CODECOV/ColorPalett: +.. _CODECOVER/ColorPalett: Color Paletts ************* @@ -289,7 +289,7 @@ Color Paletts :width: 350 px -.. _CODECOV/Styling: +.. _CODECOVER/Styling: Custom CSS Styling ****************** diff --git a/doc/Dependency.rst b/doc/Dependency.rst index 5e477e6b..d12d2239 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -3,14 +3,27 @@ Dependencies ############ -.. |img-pyTooling-lib-status| image:: https://img.shields.io/librariesio/release/pypi/sphinx-reports - :alt: Libraries.io status for latest release - :height: 22 - :target: https://libraries.io/github/pyTooling/sphinx-reports -.. |img-pyTooling-vul-status| image:: https://img.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports - :alt: Snyk Vulnerabilities for GitHub Repo - :height: 22 - :target: https://img.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports +.. only:: html + + .. |img-pyTooling-lib-status| image:: https://img.shields.io/librariesio/release/pypi/sphinx-reports + :alt: Libraries.io status for latest release + :height: 22 + :target: https://libraries.io/github/pyTooling/sphinx-reports + .. |img-pyTooling-vul-status| image:: https://img.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports + :alt: Snyk Vulnerabilities for GitHub Repo + :height: 22 + :target: https://raster.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports + +.. only:: latex + + .. |img-pyTooling-lib-status| image:: https://raster.shields.io/librariesio/release/pypi/sphinx-reports + :alt: Libraries.io status for latest release + :height: 22 + :target: https://libraries.io/github/pyTooling/sphinx-reports + .. |img-pyTooling-vul-status| image:: https://raster.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports + :alt: Snyk Vulnerabilities for GitHub Repo + :height: 22 + :target: https://raster.shields.io/snyk/vulnerabilities/github/pyTooling/sphinx-reports +------------------------------------------+------------------------------------------+ | `Libraries.io `_ | Vulnerabilities Summary | @@ -104,7 +117,7 @@ the mandatory dependencies too. +=====================================================================+=============+========================================================================================+======================+ | `pytest `__ | ≥9.0 | `MIT `__ | *Not yet evaluated.* | +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ -| `pytest-cov `__ | ≥7.0 | `MIT `__ | *Not yet evaluated.* | +| `pytest-cov `__ | ≥7.1 | `MIT `__ | *Not yet evaluated.* | +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ | `Coverage `__ | ≥7.13 | `Apache License, 2.0 `__ | *Not yet evaluated.* | +---------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ @@ -154,7 +167,7 @@ the mandatory dependencies too. +=================================================================================================+==============+==========================================================================================================+======================================================================================================================================================+ | `pyTooling `__ | ≥8.11 | `Apache License, 2.0 `__ | *None* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `Sphinx `__ | ≥9.0 | `BSD 3-Clause `__ | *Not yet evaluated.* | +| `Sphinx `__ | ≥9.1 | `BSD 3-Clause `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `sphinx_rtd_theme `__ | ≥3.1 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -162,11 +175,11 @@ the mandatory dependencies too. +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `autoapi `__ | ≥2.0.1 | `Apache License, 2.0 `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `sphinx_design `__ | ≥0.6 | `MIT `__ | *Not yet evaluated.* | +| `sphinx_design `__ | ≥0.7 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `sphinx-copybutton `__ | ≥0.5 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `sphinx_autodoc_typehints `__ | ≥3.6 | `MIT `__ | *Not yet evaluated.* | +| `sphinx_autodoc_typehints `__ | ≥3.10 | `MIT `__ | *Not yet evaluated.* | +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ .. TODO:: document the usage of diff --git a/doc/DocCov/index.rst b/doc/DocCov/index.rst index e2788323..d9b4ba9a5 100644 --- a/doc/DocCov/index.rst +++ b/doc/DocCov/index.rst @@ -1,4 +1,4 @@ -.. _DOCCOV: +.. _DOCCOVER: Documentation Coverage ###################### @@ -10,7 +10,7 @@ Documentation Coverage The :rst:dir:`report:doc-coverage` directive generates a documentation coverage report summary table. The documentation coverage reports need to be configured in Sphinx's ``conf.py`` for pre-analysis and data aggregation - (:ref:`see below ` for details). This also allows the directive to supports multiple documentation + (:ref:`see below ` for details). This also allows the directive to supports multiple documentation coverage reports per Sphinx documentation. Each documentation coverage report is referenced by the :rst:dir:`reportid ` option, which matches the dictionary key used in the configuration file. @@ -55,7 +55,7 @@ Documentation Coverage .. image:: ../_static/DocCoverage.png -.. _DOCCOV/Config: +.. _DOCCOVER/Config: Configuration Entries in :file:`conf.py` **************************************** @@ -130,7 +130,7 @@ Configuration Entries in :file:`conf.py` } -.. _DOCCOV/Example: +.. _DOCCOVER/Example: Example Document **************** @@ -150,7 +150,7 @@ The second file shows how to integrate that document into the navigation bar / * .. code-block:: ReST - .. _DOCCOV: + .. _DOCCOVER: Documentation Coverage Report ############################# @@ -194,7 +194,7 @@ The second file shows how to integrate that document into the navigation bar / * :hidden: -.. _DOCCOV/Directives: +.. _DOCCOVER/Directives: Sphinx Directives ***************** @@ -241,7 +241,7 @@ The following directives are provided for visualizing documentation coverage rep * ``vertical-table`` -.. _DOCCOV/Roles: +.. _DOCCOVER/Roles: Sphinx Roles ************ @@ -249,7 +249,7 @@ Sphinx Roles *There are no roles defined.* -.. _DOCCOV/ColorPalett: +.. _DOCCOVER/ColorPalett: Color Paletts ************* diff --git a/doc/Overview.rst b/doc/Overview.rst index c88b872f..d39df681 100644 --- a/doc/Overview.rst +++ b/doc/Overview.rst @@ -47,8 +47,8 @@ See the following :file:`doc/requirements.txt` file as an example with commonly sphinxcontrib-mermaid ~= 2.0 autoapi ~= 2.0.1 sphinx_design ~= 0.7.0 - sphinx-copybutton ~= 0.5.0 - sphinx_autodoc_typehints ~= 3.6 + sphinx-copybutton ~= 0.5.2 + sphinx_autodoc_typehints ~= 3.10 sphinx_reports ~= 1.0 # <= new entry Finally, the extension needs to be enabled in Sphinx's :file:`conf.py`, so the extension is loaded by Sphinx. diff --git a/doc/Unittest/index.rst b/doc/Unittest/index.rst index 0d1b541e..61de9d5e 100644 --- a/doc/Unittest/index.rst +++ b/doc/Unittest/index.rst @@ -1,4 +1,4 @@ -.. _UNITTEST: +.. _UNITTESTING: Unit Test Summary ################# @@ -10,7 +10,7 @@ Unit Test Summary The :rst:dir:`report:unittest-summary` directive generates a unittest report summary table. The unittest report file(s) need to be configured in Sphinx's ``conf.py`` for pre-analysis and data aggregation - (:ref:`see below ` for details). This also allows the directive to supports multiple unittest + (:ref:`see below ` for details). This also allows the directive to supports multiple unittest reports per Sphinx documentation. Each unittest report is referenced by the :rst:dir:`report ` option, which matches the dictionary key used in the configuration file. @@ -72,7 +72,7 @@ Unit Test Summary .. tab-item:: Only Testsuites - .. image:: ../_static/Unittest_OnlyTestsuites.png + .. #image:: ../_static/Unittest_OnlyTestsuites.png .. tab-item:: Testsuites and Testcases :selected: @@ -80,7 +80,7 @@ Unit Test Summary .. image:: ../_static/Unittest.png -.. _UNITTEST/Config: +.. _UNITTESTING/Config: Configuration Entries in :file:`conf.py` **************************************** @@ -120,7 +120,7 @@ Configuration Entries in :file:`conf.py` } -.. _UNITTEST/Example: +.. _UNITTESTING/Example: Example Document **************** @@ -171,7 +171,7 @@ The second file shows how to integrate that document into the navigation bar / * :hidden: -.. _UNITTEST/Directives: +.. _UNITTESTING/Directives: Sphinx Directives ***************** @@ -213,7 +213,7 @@ The following directives are provided for visualizing unittest reports. -.. _UNITTEST/Roles: +.. _UNITTESTING/Roles: Sphinx Roles ************ @@ -222,7 +222,7 @@ Sphinx Roles -.. _UNITTEST/Styling: +.. _UNITTESTING/Styling: Custom CSS Styling ****************** diff --git a/doc/conf.py b/doc/conf.py index 268341eb..3baf5774 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,19 +1,29 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -from sys import path as sys_path -from os.path import abspath -from pathlib import Path -from json import loads +from sys import path as sys_path +from os.path import abspath +from pathlib import Path +from textwrap import dedent from pyTooling.Packaging import extractVersionInformation +# ============================================================================== +# Project configuration +# ============================================================================== +githubNamespace = "pyTooling" +githubProject = pythonProject = "sphinx_reports" +directoryName = pythonProject.replace('.', '/') + + +# ============================================================================== +# Project paths +# ============================================================================== ROOT = Path(__file__).resolve().parent sys_path.insert(0, abspath(".")) sys_path.insert(0, abspath("..")) -sys_path.insert(0, abspath("../sphinx_reports")) -# sys_path.insert(0, abspath("_extensions")) +sys_path.insert(0, abspath(f"../{directoryName}")) # ============================================================================== @@ -22,12 +32,10 @@ # 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 = "sphinx_reports" -directoryName = project.replace('.', '/') - packageInformationFile = Path(f"../{directoryName}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) +project = pythonProject author = versionInformation.Author copyright = versionInformation.Copyright version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. @@ -70,14 +78,6 @@ rst_prolog = "" -# ============================================================================== -# Options for HTML output -# ============================================================================== -html_context = {} -ctx = ROOT / "context.json" -if ctx.is_file(): - html_context.update(loads(ctx.open("r", encoding="utf-8").read())) - # ============================================================================== # Options for HTML output # ============================================================================== @@ -96,11 +96,11 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -html_logo = str(Path(html_static_path[0]) / "logo.png") -html_favicon = str(Path(html_static_path[0]) / "icon.png") +html_logo = str(Path(html_static_path[0]) / "logo.png") # logo.svg +html_favicon = str(Path(html_static_path[0]) / "icon.png") # favicon.png # Output file base name for HTML help builder. -htmlhelp_basename = "sphinx_reportsDoc" +htmlhelp_basename = f"{project}Doc" # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. @@ -111,52 +111,58 @@ # Python settings # ============================================================================== modindex_common_prefix = [ - f"{project}." + f"{pythonProject}." ] # ============================================================================== # Options for LaTeX / PDF output # ============================================================================== -from textwrap import dedent - +latex_engine = "lualatex" +latex_use_xindy = False latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - "papersize": "a4paper", - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - "preamble": dedent(r""" - % ================================================================================ - % User defined additional preamble code - % ================================================================================ - % Add more Unicode characters for pdfLaTeX. - % - Alternatively, compile with XeLaTeX or LuaLaTeX. - % - https://GitHub.com/sphinx-doc/sphinx/issues/3511 - % - \ifdefined\DeclareUnicodeCharacter - \DeclareUnicodeCharacter{2265}{$\geq$} - \DeclareUnicodeCharacter{21D2}{$\Rightarrow$} - \fi - - - % ================================================================================ - """), - - # Latex figure (float) alignment - #'figure_align': 'htbp', + "papersize": "a4paper", # The paper size ('letterpaper' or 'a4paper'). + "pointsize": "10pt", # The font size ('10pt', '11pt' or '12pt'). + "inputenc": "", # Let LuaLaTeX handle input encoding + "utf8extra": "", + "polyglossia": "", + "babel": r"\usepackage[english]{babel}", + "fontenc": r"\usepackage{fontspec}", # Disable the default T1 font encoding (Essential for LuaLaTeX) + "fontpkg": dedent("""\ + \\usepackage{unicode-math} + + % Set the Text Fonts (Libertinus) + \\setmainfont{Libertinus Serif} + \\setsansfont{Libertinus Sans} + \\setmonofont{Libertinus Mono} + \\setmathfont{Libertinus Math} + + % Set Symbol font + \\usepackage{newunicodechar} + \\newfontfamily{\\emojifont}[Renderer=OpenType]{NotoColorEmoji.ttf} + \\usepackage{pytooling} + \\newunicodechar{❓}{{\\emojifont ❓}} % Black Question Mark Ornament U+2753 + \\newunicodechar{❗}{{\\emojifont ❗}} % Heavy Exclamation Mark Symbol U+2757 + \\newunicodechar{➖}{{\\emojifont ➖}} % Heavy Minus Sign U+2796 + """), + "passoptionstopackages": dedent("""\ + \\PassOptionsToPackage{verbatimvisiblespace=\\ }{sphinx} + """), +# "sphinxsetup": "verbatimvisiblespace=\\textvisiblespace" +# "figure_align": "htbp", # Latex figure (float) alignment + "makeindex": r"\usepackage[columns=1]{idxlayout}\makeindex", + "printindex": r"\def\twocolumn[#1]{#1}\printindex", } + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - "sphinx_reports.tex", - "The sphinx_reports Documentation", - "Patrick Lehmann", - "manual" + f"{pythonProject}.tex", + f"The {pythonProject.replace("_", r"\_")} Documentation", + "Patrick Lehmann", + "manual" ), ] @@ -193,6 +199,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3", None), "pyTool": ("https://pyTooling.github.io/pyTooling/", None), + "edarpt": ("https://edaa.org.github.io/pyEDAA.Reports/", None), } @@ -216,11 +223,12 @@ # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - "gh": ("https://GitHub.com/%s", "gh:%s"), - "ghissue": ("https://GitHub.com/pytooling/sphinx_reports/issues/%s", "issue #%s"), - "ghpull": ("https://GitHub.com/pytooling/sphinx_reports/pull/%s", "pull request #%s"), - "ghsrc": ("https://GitHub.com/pytooling/sphinx_reports/blob/main/%s", None), - "wiki": ("https://en.wikipedia.org/wiki/%s", None), + "gh": (f"https://GitHub.com/%s", "%s"), + "ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"), + "ghpull": (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"), + "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), + "pypi": ( "https://PyPI.org/project/%s", "%s"), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), } @@ -233,6 +241,8 @@ # ============================================================================== # SphinxContrib.Mermaid # ============================================================================== +mermaid_cmd = "mmdc" +mermaid_cmd_shell = True mermaid_params = [ '--backgroundColor', 'transparent', ] @@ -271,7 +281,7 @@ report_codecov_packages = { "src": { - "name": f"{project}", + "name": f"{pythonProject}", "json_report": "../report/coverage/coverage.json", "fail_below": 80, "levels": "default" @@ -280,7 +290,7 @@ report_doccov_packages = { "src": { - "name": f"{project}", + "name": f"{pythonProject}", "directory": f"../{directoryName}", "fail_below": 80, "levels": "default" @@ -316,9 +326,9 @@ # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - project: { + pythonProject: { "template": "module", - "output": project, + "output": pythonProject, "override": True } } diff --git a/doc/requirements.txt b/doc/requirements.txt index 485b36e0..401dbde8 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,7 @@ -r ../requirements.txt # Enforce latest version on ReadTheDocs -#sphinx >= 9.0, < 10.0 +#sphinx >= 9.1, < 10.0 #docutils >= 0.22.0 #docutils_stubs ~= 0.0.22 @@ -12,5 +12,5 @@ sphinx_rtd_theme ~= 3.1 sphinxcontrib-mermaid ~= 2.0 autoapi ~= 2.0.1 sphinx_design ~= 0.7.0 -sphinx-copybutton ~= 0.5.0 -sphinx_autodoc_typehints ~= 3.6 +sphinx-copybutton ~= 0.5.2 +sphinx_autodoc_typehints ~= 3.10 diff --git a/doc/shields.inc b/doc/shields.inc index 8033740e..74cb116e 100644 --- a/doc/shields.inc +++ b/doc/shields.inc @@ -18,7 +18,7 @@ :alt: Code license :height: 22 :target: Code-License.html -.. |SHIELD:png:SphinxReports-src-license| image:: https://img.shields.io/pypi/l/sphinx-reports?longCache=true&style=flat-square&logo=Apache&label=code +.. |SHIELD:png:SphinxReports-src-license| image:: https://raster.shields.io/pypi/l/sphinx-reports?longCache=true&style=flat-square&logo=Apache&label=code :alt: Code license :height: 22 :target: https://GitHub.com/pyTooling/sphinx-reports/blob/main/LICENSE.md diff --git a/doc/unittests/index.rst b/doc/unittests/index.rst index 32022017..a9556763 100644 --- a/doc/unittests/index.rst +++ b/doc/unittests/index.rst @@ -1,3 +1,5 @@ +.. _UNITTEST: + Unittest Summary Report ####################### diff --git a/pyproject.toml b/pyproject.toml index f3eca8a2..9daae46f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,6 @@ [build-system] requires = [ "setuptools >= 80.0", - "wheel ~= 0.45.0", "pyTooling ~= 8.11" ] build-backend = "setuptools.build_meta" diff --git a/requirements.txt b/requirements.txt index 6f30248b..13990044 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ pyTooling >= 8.0 -pyEDAA.Reports ~= 0.17.0 -sphinx >= 9.0, < 10.0 +pyEDAA.Reports ~= 0.17.3 +sphinx >= 9.1, < 10.0 docutils >= 0.22.0 docutils_stubs >= 0.0.22 diff --git a/setup.py b/setup.py index 1fc4c97c..aa003e51 100644 --- a/setup.py +++ b/setup.py @@ -55,7 +55,7 @@ "Topic :: Software Development :: Testing :: Unit", ], developmentStatus="beta", - pythonVersions=("3.11", "3.12", "3.13", "3.14"), + pythonVersions=("3.12", "3.13", "3.14"), # dropped 3.11 due to Sphinx 9.1 dropping 3.11. dataFiles={ "sphinx_reports": ["static/*.css"] }, diff --git a/sphinx_reports/Common.py b/sphinx_reports/Common.py index e34875b3..29b6fc8c 100644 --- a/sphinx_reports/Common.py +++ b/sphinx_reports/Common.py @@ -32,12 +32,16 @@ **Common exceptions, classes and helper functions.** """ from enum import Flag -from typing import List +from typing import Callable, Any from pyTooling.Decorators import export from sphinx.errors import ExtensionError +type visitFunc = Callable[[Any, Any], Any] +type departFunc = Callable[[Any, Any], Any] + + @export class ReportExtensionError(ExtensionError): pass diff --git a/sphinx_reports/HTML.py b/sphinx_reports/HTML.py new file mode 100644 index 00000000..44efc776 --- /dev/null +++ b/sphinx_reports/HTML.py @@ -0,0 +1,67 @@ +# ==================================================================================================================== # +# _ _ _ # +# ___ _ __ | |__ (_)_ __ __ __ _ __ ___ _ __ ___ _ __| |_ ___ # +# / __| '_ \| '_ \| | '_ \\ \/ /____| '__/ _ \ '_ \ / _ \| '__| __/ __| # +# \__ \ |_) | | | | | | | |> <_____| | | __/ |_) | (_) | | | |_\__ \ # +# |___/ .__/|_| |_|_|_| |_/_/\_\ |_| \___| .__/ \___/|_| \__|___/ # +# |_| |_| # +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# License: # +# ==================================================================================================================== # +# Copyright 2026-2026 Patrick Lehmann - Bötzingen, Germany # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +# # +# SPDX-License-Identifier: Apache-2.0 # +# ==================================================================================================================== # +# +from typing import Tuple + +from sphinx.writers.html5 import HTML5Translator + +from pyTooling.Decorators import export +from sphinx_reports.Common import visitFunc, departFunc +from sphinx_reports.Node import Landscape + + +__all__ = ["translateLandscape"] + +@export +def visit_Landscape(translator: HTML5Translator, node: Landscape) -> None: + """ + Call back function for visiting a :class:`Landscape`. + + This function has no actions for HTML5. + + :param translator: The HTML5 translator instance. + :param node: The current node being visited. + """ + + +@export +def depart_Landscape(translator: HTML5Translator, node: Landscape) -> None: + """ + Call back function for departing a :class:`Landscape`. + + This function has no actions for HTML5. + + :param translator: The HTML5 translator instance. + :param node: The current node being departed. + """ + + +translateLandscape: Tuple[visitFunc, departFunc] = (visit_Landscape, depart_Landscape) +"""A tuple combining both ``visit_*`` and ``depart_*`` call back functions for a :class:`Landscape` node.""" diff --git a/sphinx_reports/LaTeX.py b/sphinx_reports/LaTeX.py new file mode 100644 index 00000000..536971d5 --- /dev/null +++ b/sphinx_reports/LaTeX.py @@ -0,0 +1,70 @@ +# ==================================================================================================================== # +# _ _ _ # +# ___ _ __ | |__ (_)_ __ __ __ _ __ ___ _ __ ___ _ __| |_ ___ # +# / __| '_ \| '_ \| | '_ \\ \/ /____| '__/ _ \ '_ \ / _ \| '__| __/ __| # +# \__ \ |_) | | | | | | | |> <_____| | | __/ |_) | (_) | | | |_\__ \ # +# |___/ .__/|_| |_|_|_| |_/_/\_\ |_| \___| .__/ \___/|_| \__|___/ # +# |_| |_| # +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# License: # +# ==================================================================================================================== # +# Copyright 2026-2026 Patrick Lehmann - Bötzingen, Germany # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +# # +# SPDX-License-Identifier: Apache-2.0 # +# ==================================================================================================================== # +# +from typing import Tuple + +from sphinx.writers.latex import LaTeXTranslator + +from pyTooling.Decorators import export +from sphinx_reports.Common import visitFunc, departFunc +from sphinx_reports.Node import Landscape + + +__all__ = ["translateLandscape"] + + +@export +def visit_Landscape(translator: LaTeXTranslator, node: Landscape) -> None: + """ + Call back function for visiting a :class:`Landscape`. + + This function begins a ``landscape`` environment in LaTeX. + + :param translator: The LaTeX translator instance. + :param node: The current node being visited. + """ + translator.body.append(r'\begin{landscape}') + + +@export +def depart_Landscape(translator: LaTeXTranslator, node: Landscape) -> None: + """ + Call back function for departing a :class:`Landscape`. + + This function ends a ``landscape`` environment in LaTeX. + + :param translator: The LaTeX translator instance. + :param node: The current node being departed. + """ + translator.body.append(r'\end{landscape}') + + +translateLandscape: Tuple[visitFunc, departFunc] = (visit_Landscape, depart_Landscape) +"""A tuple combining both ``visit_*`` and ``depart_*`` call back functions for a :class:`Landscape` node.""" diff --git a/sphinx_reports/Node.py b/sphinx_reports/Node.py new file mode 100644 index 00000000..d53130b8 --- /dev/null +++ b/sphinx_reports/Node.py @@ -0,0 +1,40 @@ +# ==================================================================================================================== # +# _ _ _ # +# ___ _ __ | |__ (_)_ __ __ __ _ __ ___ _ __ ___ _ __| |_ ___ # +# / __| '_ \| '_ \| | '_ \\ \/ /____| '__/ _ \ '_ \ / _ \| '__| __/ __| # +# \__ \ |_) | | | | | | | |> <_____| | | __/ |_) | (_) | | | |_\__ \ # +# |___/ .__/|_| |_|_|_| |_/_/\_\ |_| \___| .__/ \___/|_| \__|___/ # +# |_| |_| # +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# License: # +# ==================================================================================================================== # +# Copyright 2026-2026 Patrick Lehmann - Bötzingen, Germany # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +# # +# SPDX-License-Identifier: Apache-2.0 # +# ==================================================================================================================== # +# +from docutils.nodes import container + +from pyTooling.Decorators import export + + +@export +class Landscape(container): + """ + A container node used in LaTeX to render content in landscape view in PDF pages. + """ diff --git a/sphinx_reports/Unittest.py b/sphinx_reports/Unittest.py index a9928109..d83b0100 100644 --- a/sphinx_reports/Unittest.py +++ b/sphinx_reports/Unittest.py @@ -45,6 +45,7 @@ from sphinx.config import Config from sphinx_reports.Common import ReportExtensionError +from sphinx_reports.Node import Landscape from sphinx_reports.Sphinx import strip, stripAndNormalize, BaseDirective @@ -54,12 +55,12 @@ class report_DictType(TypedDict): @export class ShowTestcases(Flag): - passed = 1 - failed = 2 - skipped = 4 - excluded = 8 - errors = 16 - aborted = 32 + passed = 1 + failed = 2 + skipped = 4 + excluded = 8 + errors = 16 + aborted = 32 all = passed | failed | skipped | excluded | errors | aborted not_passed = all & ~passed @@ -356,7 +357,7 @@ def renderSummary(self, tableBody: nodes.tbody, testsuiteSummary: TestsuiteSumma tableRow += nodes.entry("", nodes.Text(f"{self._formatTimedelta(testsuiteSummary.TotalDuration)}")) def run(self) -> List[nodes.Node]: - container = nodes.container() + container = Landscape() try: self._CheckOptions() diff --git a/sphinx_reports/__init__.py b/sphinx_reports/__init__.py index 993901e5..dfa01b04 100644 --- a/sphinx_reports/__init__.py +++ b/sphinx_reports/__init__.py @@ -43,7 +43,7 @@ __email__ = "Paebbels@gmail.com" __copyright__ = "2023-2026, Patrick Lehmann" __license__ = "Apache License, Version 2.0" -__version__ = "0.10.0" +__version__ = "0.11.0" __keywords__ = [ "Python3", "Sphinx", "Extension", "Report", "doc-string", "interrogate", "Code Coverage", "Coverage", "Documentation Coverage", "Unittest", "Dependencies", "Summary" @@ -51,9 +51,9 @@ from hashlib import md5 from pathlib import Path -from typing import TYPE_CHECKING, Any, Tuple, Dict, Optional as Nullable, TypedDict, List, Callable +from typing import TYPE_CHECKING, Any, Tuple, Dict, Optional as Nullable, TypedDict, List, Callable, Type -from docutils import nodes +from docutils.nodes import Element from sphinx.addnodes import pending_xref from sphinx.application import Sphinx from sphinx.builders import Builder @@ -65,7 +65,21 @@ from pyTooling.Common import readResourceFile from sphinx_reports import static as ResourcePackage -from sphinx_reports.Common import ReportExtensionError +from sphinx_reports.Common import ReportExtensionError, visitFunc, departFunc +from sphinx_reports.Node import Landscape +from sphinx_reports.HTML import translateLandscape as translateLandscapeAsHTML +from sphinx_reports.LaTeX import translateLandscape as translateLandscapeAsLaTeX + + +@export +class RegisteredNode(TypedDict): + """ + Type information for an entry in :attr:`ReportDomain.nodes`. + """ + name: str #: Name of the new docutils node to register. + node: Type[Element] #: The new node class to register. + html: Tuple[visitFunc, departFunc] #: A tuple of visit and depart functions rendering the new node in case of HTML output. + latex: Tuple[visitFunc, departFunc] #: A tuple of visit and depart functions rendering the new node in case of LaTeX output. @export @@ -106,6 +120,17 @@ class ReportDomain(Domain): dependencies: List[str] = [ ] #: A list of other extensions this domain depends on. + latexPackages: Tuple[str, ...] = ( + "pdflscape", + ) + nodes: Tuple[RegisteredNode, ...] = ( + { "name": "Landscape", + "node": Landscape, + "html": translateLandscapeAsHTML, + "latex": translateLandscapeAsLaTeX + }, + ) + from sphinx_reports.CodeCoverage import CodeCoverage, CodeCoverageLegend, ModuleCoverage from sphinx_reports.DocCoverage import DocStrCoverage, DocCoverageLegend from sphinx_reports.Dependency import DependencyTable @@ -262,8 +287,8 @@ def resolve_xref( typ: str, target: str, node: pending_xref, - contnode: nodes.Element - ) -> Nullable[nodes.Element]: + contnode: Element + ) -> Nullable[Element]: raise NotImplementedError() @@ -291,6 +316,14 @@ def setup(sphinxApplication: Sphinx) -> "setup_ReturnType": """ sphinxApplication.add_domain(ReportDomain) + # Request new LaTeX package dependencies + for latexPackage in ReportDomain.latexPackages: + sphinxApplication.add_latex_package(latexPackage) + + # Register new docutil nodes. + for newNode in ReportDomain.nodes: + sphinxApplication.add_node(newNode["node"], html=newNode["html"], latex=newNode["latex"]) + # Register callbacks for eventName, callbacks in ReportDomain.callbacks.items(): for callback in callbacks: @@ -303,6 +336,6 @@ def setup(sphinxApplication: Sphinx) -> "setup_ReturnType": return { "version": __version__, # version of the extension "env_version": int(__version__.split(".")[0]), # version of the data structure stored in the environment - 'parallel_read_safe': False, # Not yet evaluated, thus false + 'parallel_read_safe': False, # TODO: Not yet evaluated, thus false 'parallel_write_safe': True, # Internal data structure is used read-only, thus no problems will occur by parallel writing. } diff --git a/tests/unit/requirements.txt b/tests/unit/requirements.txt index a2ffbaa9..b20db853 100644 --- a/tests/unit/requirements.txt +++ b/tests/unit/requirements.txt @@ -5,4 +5,4 @@ Coverage ~= 7.13 # Test Runner pytest ~= 9.0 -pytest-cov ~= 7.0 +pytest-cov ~= 7.1