v0.1.0

.btd.yml

@@ -0,0 +1,9 @@
+input: doc
+output: _build
+requirements: requirements.txt
+target: gh-pages
+formats: [ html ]
+images:
+  base: btdi/sphinx:pytooling
+  latex: btdi/latex
+theme: https://codeload.GitHub.com/buildthedocs/sphinx.theme/tar.gz/v1

.github/workflows/Pipeline.yml

@@ -0,0 +1,154 @@
+name: Pipeline
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  UnitTestingParams:
+    uses: pyTooling/Actions/.github/workflows/Parameters.yml@cov
+    with:
+      name: sphinx-eports
+#      python_version_list: "3.8 3.9 3.10 3.11 3.12 pypy-3.8 pypy-3.9 pypy-3.10"
+#      disable_list: "windows:pypy-3.8 windows:pypy-3.9 windows:pypy-3.10"
+
+  UnitTesting:
+    uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@cov
+    needs:
+      - UnitTestingParams
+    with:
+      jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }}
+      requirements: "-r tests/unit/requirements.txt"
+      pacboy: "msys/git"
+      unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
+      coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}
+
+#  Coverage:
+#    uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@cov
+#    needs:
+#      - UnitTestingParams
+#    with:
+#      python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
+#      artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
+#    secrets:
+#      codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+
+  StaticTypeCheck:
+    uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@cov
+    needs:
+      - UnitTestingParams
+    with:
+      python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
+      commands: |
+        mypy --html-report htmlmypy -p sphinx_reports
+      html_report: 'htmlmypy'
+      html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).statictyping_html }}
+
+  PublishCoverageResults:
+    uses: pyTooling/Actions/.github/workflows/PublishCoverageResults.yml@cov
+    needs:
+      - UnitTestingParams
+      - UnitTesting
+#      - Coverage
+    with:
+#      coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}
+#      coverage_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_xml }}
+#      coverage_json_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
+      coverage_html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
+    secrets:
+      codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+
+  PublishTestResults:
+    uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@cov
+    needs:
+      - UnitTesting
+
+  Package:
+    uses: pyTooling/Actions/.github/workflows/Package.yml@cov
+    needs:
+      - UnitTestingParams
+      - UnitTesting
+#      - Coverage
+    with:
+      python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
+      artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }}
+
+#  VerifyDocs:
+#    uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@cov
+#    needs:
+#      - UnitTestingParams
+#    with:
+#      python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
+
+  BuildTheDocs:
+    uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@cov
+    needs:
+      - UnitTestingParams
+#      - VerifyDocs
+    with:
+      artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
+
+  PublishToGitHubPages:
+    uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@cov
+    needs:
+      - UnitTestingParams
+      - BuildTheDocs
+#      - Coverage
+      - PublishCoverageResults
+      - StaticTypeCheck
+    with:
+      doc: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
+      coverage: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
+      typing: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).statictyping_html }}
+
+  ReleasePage:
+    uses: pyTooling/Actions/.github/workflows/Release.yml@cov
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - UnitTesting
+#      - Coverage
+#      - StaticTypeCheck
+      - Package
+      - PublishToGitHubPages
+
+  PublishOnPyPI:
+    uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@cov
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - UnitTestingParams
+      - ReleasePage
+    with:
+      python_version: ${{ needs.UnitTestingParams.outputs.python_version }}
+      requirements: -r dist/requirements.txt
+      artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }}
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+  ArtifactCleanUp:
+    uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@cov
+    needs:
+      - UnitTestingParams
+      - UnitTesting
+#      - Coverage
+      - StaticTypeCheck
+#      - BuildTheDocs
+      - PublishToGitHubPages
+      - PublishCoverageResults
+      - PublishTestResults
+    with:
+      package: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }}
+      remaining: |
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_html }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_xml }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}-*
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_html }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_xml }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_json }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).statictyping_html }}
+        ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}

.gitignore

@@ -20,8 +20,8 @@ report/
 
 # Sphinx
 doc/_build/
-doc/sphinx-reports/**/*.*
-!doc/sphinx-reports/index.rst
+doc/sphinx_reports/**/*.*
+!doc/sphinx_reports/index.rst
 
 # BuildTheDocs
 doc/_theme/**/*.*

README.md

@@ -1,16 +1,120 @@
+[![Sourcecode on GitHub](https://img.shields.io/badge/pyTooling-sphinx-reports-323131.svg?logo=github&longCache=true)](https://github.com/pyTooling/sphinx-reports)
+[![License](https://img.shields.io/badge/code%20license-Apache%20License%2C%202.0-lightgrey?logo=GitHub)](LICENSE.md)
+[![GitHub tag (latest SemVer incl. pre-release)](https://img.shields.io/github/v/tag/pyTooling/sphinx-reports?logo=GitHub&include_prereleases)](https://github.com/pyTooling/sphinx-reports/tags)
+[![GitHub release (latest SemVer incl. including pre-releases)](https://img.shields.io/github/v/release/pyTooling/sphinx-reports?logo=GitHub&include_prereleases)](https://github.com/pyTooling/sphinx-reports/releases/latest)
+[![GitHub release date](https://img.shields.io/github/release-date/pyTooling/sphinx-reports?logo=GitHub&)](https://github.com/pyTooling/sphinx-reports/releases)  
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/pyTooling/sphinx-reports/Test,%20Coverage%20and%20Release?label=Workflow&logo=GitHub)](https://github.com/pyTooling/sphinx-reports/actions?query=workflow%3A%22Test%2C+Coverage+and+Release%22)
+[![PyPI](https://img.shields.io/pypi/v/sphinx-reports?logo=PyPI)](https://pypi.org/project/sphinx-reports/)
+![PyPI - Status](https://img.shields.io/pypi/status/sphinx-reports?logo=PyPI)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-reports?logo=PyPI)
+[![Dependent repos (via libraries.io)](https://img.shields.io/librariesio/dependent-repos/pypi/sphinx-reports)](https://github.com/pyTooling/sphinx-reports/network/dependents)  
+[![Libraries.io status for latest release](https://img.shields.io/librariesio/release/pypi/sphinx-reports)](https://libraries.io/github/pyTooling/sphinx-reports)
+[![Requires.io](https://img.shields.io/requires/github/pyTooling/sphinx-reports)](https://requires.io/github/pyTooling/sphinx-reports/requirements/?branch=master)  
+[![Codacy - Quality](https://img.shields.io/codacy/grade/b63aac7ef7e34baf829f11a61574bbaf?logo=Codacy)](https://www.codacy.com/manual/pyTooling/sphinx-reports)
+[![Codacy - Coverage](https://img.shields.io/codacy/coverage/b63aac7ef7e34baf829f11a61574bbaf?logo=Codacy)](https://www.codacy.com/manual/pyTooling/sphinx-reports)
+[![Codecov - Branch Coverage](https://img.shields.io/codecov/c/github/pyTooling/sphinx-reports?logo=Codecov)](https://codecov.io/gh/pyTooling/sphinx-reports)
+[![Libraries.io SourceRank](https://img.shields.io/librariesio/sourcerank/pypi/sphinx-reports)](https://libraries.io/github/pyTooling/sphinx-reports/sourcerank)  
+<!-- [![Read the Docs](https://img.shields.io/readthedocs/sphinx-reports)](https://pyVersioning.readthedocs.io/en/latest/) -->
+
+
 # Sphinx Reports
 
-## Supported Report Formats
+The Sphinx extension `sphinx_reports` offers a set of directives to integrate reports and summaries into the
+documentation generated by Sphinx.
+
+Supported format reports are:
+* ✅ Documentation coverage (by `docstr_coverage` (or `interrogate`?))
+* 🚧 Code coverage (by `Coverage.py`)
+* 🚧 Unit Test summaries (by `pytest`)
+* 🚧 Dependencies (reading `requirements.txt` files)
+
+## Extension Configuration
+
+This README demonstrates a quick and minimal configuration for the Sphinx extension and it's provided directives. See
+the [sphinx-reports documentation](https://pyTooling.github.io/sphinx-reports) for more details.
+
+At first, add the extension name to the list of extensions in `conf.py`, so the extension is loaded by Sphinx.
+
+```Python
+# Sphinx extensions
+extensions = [
+  # ...
+  "sphinx_reports",
+]
+```
+
+Each report directive might require an individual configuration, therefore see the next sections for details.
+
+## Documentation Coverage
+
+    DocCov: write introduction
+
+
+### Quick Configuration
+
+This is a quick and minimal configuration for the *documentation coverage* directives.
+See [documentation coverage](https://pyTooling.github.io/sphinx-reports/DocCov/index.html) documentation for more
+details.
+
+1. Configure one or more Python packages for documentation coverage analysis in `conf.py` by adding a new 'section' 
+   defining some configuration variables. Each package is identified by an ID, which is later referred to by the report
+   directive. Here, the ID is called `src` (dictionary key). Each package needs 4 configuration entries:
+
+   * `name`  
+     Name of the Python package[^PkgNameVsPkgDir].
+   * `directory`  
+     The directory of the package to analyze.
+   * `fail_below`  
+     An integer value in range 0..100, for when a documentation coverage is considered FAILED.
+   * `levels`  
+     A dictionary of coverage limits, their description and CSS style classes.
+
+   ```Python
+   # ==============================================================================
+   # Sphinx-reports - DocCov
+   # ==============================================================================
+   report_doccov_packages = {
+     "src": {
+       "name":       "myPackage",
+       "directory":  "../myPackage",
+       "fail_below": 80,
+       "levels": {
+         30:  {"class": "doccov-below30",  "desc": "almost undocumented"},
+         50:  {"class": "doccov-below50",  "desc": "poorly documented"},
+         80:  {"class": "doccov-below80",  "desc": "roughly documented"},
+         90:  {"class": "doccov-below90",  "desc": "well documented"},
+         100: {"class": "doccov-below100", "desc": "excellent documented"},
+       },
+     }
+   }
+   ```
+2. Add the `doc-coverage` into your Restructured Text (ReST) document.
+
+   * `packageid`  
+     The ID used in `conf.py` to describe a Python package.
+   * `legend` (optional)  
+     Position of the legend (`NoLegend`, `Top`, `Bottom`, `Both`)
+
+   ```Python
+   .. report:doc-coverage::
+      :packageid: src
+   ```
+
+
+## Code Coverage
+
+    CodeCov: write introduction
+
+
+## Unit Test Summary
+
+    UnitTest: write introduction
+
+
+## Dependencies
+
+    Dep: write introduction
 
-* Python documentation coverage (doc-string coverage)
-  * `docstr_coverage`
-  * `interrogate`
-* Python code coverage (line/statement and branch coverage)
-  * `coverage.py`
-* Unit test summary
-  * `pytest`
-* Static type analysis
-  * `mypy`
 
 ## Contributors
 
@@ -21,7 +125,7 @@
 
 This Python package (source code) is licensed under [Apache License 2.0](LICENSE.md).
 
-<!-- The accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0). -->
+The accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0).
 
 
 -------------------------

dist/requirements.txt

@@ -0,0 +1,2 @@
+wheel >= 0.40.0
+twine >= 4.0.2

doc/CodeCov/index.rst

@@ -0,0 +1,5 @@
+.. _CODECOV:
+
+Code Coverage
+#############
+