diff --git a/.btd.yml b/.btd.yml new file mode 100644 index 0000000..296c029 --- /dev/null +++ b/.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 diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..3c7043c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,30 @@ +root = true + +[*] +charset = utf-8 +# end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = tab +indent_size = 2 +tab_width = 2 + + +[*.py] +indent_style = tab +indent_size = 2 + +[*.{yml,yaml}] +indent_style = space +indent_size = 2 + +[*.{json,ini}] +indent_style = tab +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[*.rst] +indent_style = space +indent_size = 3 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b4feb0e --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# Python cache and object files +__pycache__/ +*.py[cod] + +# Coverage.py +.coverage +.cov +coverage.xml +/report/coverage + +# mypy +/report/typing + +# pytest +/report/unit + +# setuptools +/build/**/*.* +/dist/**/*.* +/*.egg-info + +# Dependencies +!requirements.txt + +# Sphinx +doc/_build/ +doc/pyTooling/**/*.* +!doc/pyTooling/index.rst + +# BuildTheDocs +doc/_theme/**/*.* + +# IntelliJ project files +/.idea/workspace.xml + +# Git files +!.git* diff --git a/Actions/__init__.py b/Actions/__init__.py new file mode 100644 index 0000000..c79a865 --- /dev/null +++ b/Actions/__init__.py @@ -0,0 +1,37 @@ +# ==================================================================================================================== # +# _____ _ _ ____ # +# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___|___ _ __ ___ _ __ ___ ___ _ __ # +# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || | / _ \| '_ ` _ \| '_ ` _ \ / _ \| '_ \ # +# | |_) | |_| || | (_) | (_) | | | | | | (_| || |__| (_) | | | | | | | | | | | (_) | | | | # +# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____\___/|_| |_| |_|_| |_| |_|\___/|_| |_| # +# |_| |___/ |___/ # +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# License: # +# ==================================================================================================================== # +# Copyright 2017-2022 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 # +# ==================================================================================================================== # +# +"""Placeholder""" +__author__ = "Patrick Lehmann" +__email__ = "Paebbels@gmail.com" +__copyright__ = "2017-2022, Patrick Lehmann" +__license__ = "Apache License, Version 2.0" +__version__ = "0.4.4" +__keywords__ = [] diff --git a/doc/Action/Releaser.rst b/doc/Action/Releaser.rst new file mode 100644 index 0000000..d410da6 --- /dev/null +++ b/doc/Action/Releaser.rst @@ -0,0 +1,3 @@ +Releaser +######## + diff --git a/doc/Action/With-post-step.rst b/doc/Action/With-post-step.rst new file mode 100644 index 0000000..5e4154b --- /dev/null +++ b/doc/Action/With-post-step.rst @@ -0,0 +1,3 @@ +with-post-step +############## + diff --git a/doc/Action/index.rst b/doc/Action/index.rst new file mode 100644 index 0000000..be86e43 --- /dev/null +++ b/doc/Action/index.rst @@ -0,0 +1,4 @@ +Overview +######## + + diff --git a/doc/Dependency.rst b/doc/Dependency.rst new file mode 100644 index 0000000..4cf2f5d --- /dev/null +++ b/doc/Dependency.rst @@ -0,0 +1,12 @@ +Dependencies +############ + +* Parameters + + * *None* + +* PublishOnPyPI + + * actions/download-artifact + * actions/setup-python + * geekyeggo/delete-artifact diff --git a/doc/Introduction.rst b/doc/Introduction.rst new file mode 100644 index 0000000..97e99dd --- /dev/null +++ b/doc/Introduction.rst @@ -0,0 +1,3 @@ +Introduction +############ + diff --git a/doc/JobTemplate/ArtifactCleanUp.rst b/doc/JobTemplate/ArtifactCleanUp.rst new file mode 100644 index 0000000..77d65b0 --- /dev/null +++ b/doc/JobTemplate/ArtifactCleanUp.rst @@ -0,0 +1,39 @@ +ArtifactCleanUp +############### + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/BuildTheDocs.rst b/doc/JobTemplate/BuildTheDocs.rst new file mode 100644 index 0000000..20318b4 --- /dev/null +++ b/doc/JobTemplate/BuildTheDocs.rst @@ -0,0 +1,39 @@ +BuildTheDocs +############ + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/CoverageCollection.rst b/doc/JobTemplate/CoverageCollection.rst new file mode 100644 index 0000000..8b505c9 --- /dev/null +++ b/doc/JobTemplate/CoverageCollection.rst @@ -0,0 +1,45 @@ +CoverageCollection +################## + +collect code coverage data (incl. branch coverage) + with `pytest`/`pytest-cov`/`coverage.py` using a single version of Python (latest). It generates HTML and Cobertura + (XML)reports, upload the HTML report as an artifact, and upload the test results to Codecov and Codacy. Configuration + options to `pytest` and `coverage.py` should be given via section `[tool.pytest.ini_options]` and `[tool.coverage.*]` + in a `pyproject.toml` file. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/Package.rst b/doc/JobTemplate/Package.rst new file mode 100644 index 0000000..3e676aa --- /dev/null +++ b/doc/JobTemplate/Package.rst @@ -0,0 +1,41 @@ +Package +####### + +generate source and wheel packages, and upload them as an artifact. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst new file mode 100644 index 0000000..5636838 --- /dev/null +++ b/doc/JobTemplate/Parameters.rst @@ -0,0 +1,139 @@ +Parameters +########## + +The `Parameters` job template is a workaround for the limitations of GitHub Actions to handle global variables in +GitHub Actions workflows (see [actions/runner#480](https://github.com/actions/runner/issues/480)). + +It generates output parameters with artifact names and a job matrix to be used in later running jobs. + +Instantiation +************* + +Simple Example +============== + +The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only +requires a `name` parameter to create the artifact names. + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0 + with: + name: pyTooling + +Complex Example +=============== + +The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The +first job `UnitTestingParams` might be used to create a job matrix of unit tests. It creates the cross of default +systems (Windows, Ubuntu, MacOS, MinGW64) and the given list of Python versions including some mypy versions. In +addition a list of excludes (marked as :deletetion:`deletion`) and includes (marked as :additions:`additions`) is handed +over resulting in the following combinations: + ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| Version | 3.7 | 3.8 | 3.9 | 3.10 | 3.11 | 3.12.a1 | mypy-3.7 | mypy-3.8 | mypy-3.9 | ++=========+=============+=============+=============+==============+=========================+=========+==========+==============================+==============================+ +| Windows | windows:3.7 | windows:3.8 | windows:3.9 | windows:3.10 | | | | :deletion:`windows:mypy-3.8` | :deletion:`windows:mypy-3.9` | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| Ubuntu | ubuntu:3.7 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | :addition:`ubuntu:3.11` | | | ubuntu:mypy-3.8 | ubuntu:mypy-3.9 | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| MacOS | macos:3.7 | macos:3.8 | macos:3.9 | macos:3.10 | :addition:`macos:3.11` | | | macos:mypy-3.8 | macos:mypy-3.9 | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| MSYS | | | | | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| MinGW32 | | | | | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| MinGW64 | | | | mingw64:3.10 | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| Clang32 | | | | | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| Clang64 | | | | | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ +| UCRT64 | | | | | | | | | | ++---------+-------------+-------------+-------------+--------------+-------------------------+---------+----------+------------------------------+------------------------------+ + + + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + UnitTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0 + with: + name: pyTooling + python_version_list: "3.7 3.8 3.9 3.10 pypy-3.8 pypy-3.9" + include_list: "ubuntu:3.11 macos:3.11" + exclude_list: "windows:pypy-3.8 windows:pypy-3.9" + + PerformanceTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0 + with: + name: pyTooling + python_version_list: "3.10 3.11" + system_list: "ubuntu windows macos" + + PlatformTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev + with: + name: pyTooling + python_version_list: "3.10" + system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64" + +Template Parameters +******************* + +Name +====== +The name of the library or package. + + It's used to create artifact names. + + +python_version_list +=================== + +TBD + + +system_list +=========== + +TBD + + +include_list +============ + +TBD + +exclude_list +============ + +TBD + +Template Results +**************** + +Params +====== + + +Jobs +==== + + + diff --git a/doc/JobTemplate/PublishOnPyPI.rst b/doc/JobTemplate/PublishOnPyPI.rst new file mode 100644 index 0000000..05acf85 --- /dev/null +++ b/doc/JobTemplate/PublishOnPyPI.rst @@ -0,0 +1,86 @@ +PublishOnPyPI +############# + +Publish a source (``*.tar.gz``) and wheel (``*.whl``) packages to `PyPI `__. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + jobs: + # ... + + PublishOnPyPI: + uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0 + if: startsWith(github.ref, 'refs/tags') + with: + artifact: Package + secrets: + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + +Complex Example +=============== + +.. code-block:: yaml + + jobs: + # ... + + PublishOnPyPI: + uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r0 + if: startsWith(github.ref, 'refs/tags') + needs: + - Params + - Package + with: + python_version: ${{ fromJson(needs.Params.outputs.params).python_version }} + requirements: -r dist/requirements.txt + artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.Package }} + secrets: + PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + +Template Parameters +******************* + +python_version +============== + +Python version used for uploading the package contents via `twine` to PyPI. + +**Default:** 3.11 + +requirements +============ + +List of requirements to be installed for uploading the package contents to PyPI. + +**Default:** wheel, twine + +artifact +======== + +Name of the artifact containing the package(s). + +Secrets +******* + +PYPI_TOKEN +========== + +The token to access the package at PyPI for uploading new data. + +Template Results +**************** + +*None* + +Dependencies +************ + +* actions/download-artifact +* actions/setup-python +* geekyeggo/delete-artifact diff --git a/doc/JobTemplate/PublishTestResults.rst b/doc/JobTemplate/PublishTestResults.rst new file mode 100644 index 0000000..cfaaf2f --- /dev/null +++ b/doc/JobTemplate/PublishTestResults.rst @@ -0,0 +1,39 @@ +PublishTestResults +################## + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/PublishToGitHubPages.rst b/doc/JobTemplate/PublishToGitHubPages.rst new file mode 100644 index 0000000..bdb70ae --- /dev/null +++ b/doc/JobTemplate/PublishToGitHubPages.rst @@ -0,0 +1,39 @@ +PublishToGitHubPages +#################### + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/Release.rst b/doc/JobTemplate/Release.rst new file mode 100644 index 0000000..0b28180 --- /dev/null +++ b/doc/JobTemplate/Release.rst @@ -0,0 +1,41 @@ +Release +####### + +publish GitHub Release. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/StaticTypeCheck.rst b/doc/JobTemplate/StaticTypeCheck.rst new file mode 100644 index 0000000..1da6930 --- /dev/null +++ b/doc/JobTemplate/StaticTypeCheck.rst @@ -0,0 +1,65 @@ +StaticTypeCheck +############### + +collect static type check result with `mypy`, and + optionally upload results as an HTML report. + Example `commands`: + + 1. Regular package + + ```yml + commands: mypy --html-report htmlmypy -p ToolName + ``` + + 2. Parent namespace package + + ```yml + commands: | + touch Parent/__init__.py + mypy --html-report htmlmypy -p ToolName + ``` + + 3. Child namespace package + + ```yml + commands: | + cd Parent + mypy --html-report ../htmlmypy -p ToolName + ``` + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/UnitTesting.rst b/doc/JobTemplate/UnitTesting.rst new file mode 100644 index 0000000..7255f9c --- /dev/null +++ b/doc/JobTemplate/UnitTesting.rst @@ -0,0 +1,43 @@ +UnitTesting +########### + +run unit test with `pytest` using multiple versions of Python, and + optionally upload results as XML reports. Configuration options to `pytest` should be given via section + `[tool.pytest.ini_options]` in a `pyproject.toml` file. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/VerifyDocs.rst b/doc/JobTemplate/VerifyDocs.rst new file mode 100644 index 0000000..d6a94f3 --- /dev/null +++ b/doc/JobTemplate/VerifyDocs.rst @@ -0,0 +1,41 @@ +VerifyDocs +########## + +extract code examples from the README and test these code snippets. + +Instantiation +************* + +Simple Example +============== + +.. code-block:: yaml + + TBD + +Complex Example +=============== + + + +.. code-block:: yaml + + TBD + +Template Parameters +******************* + +TBD 1 +===== + +TBD + +TBD 1 +===== + +TBD + +Template Results +**************** + +*None* diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst new file mode 100644 index 0000000..be86e43 --- /dev/null +++ b/doc/JobTemplate/index.rst @@ -0,0 +1,4 @@ +Overview +######## + + diff --git a/doc/License.rst b/doc/License.rst new file mode 100644 index 0000000..7df6024 --- /dev/null +++ b/doc/License.rst @@ -0,0 +1,136 @@ +.. Note:: This is a local copy of the `Apache License Version 2.0 `_. + +Apache License 2.0 +################## + +Version 2.0, January 2004 + +**TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION** + + +1. Definitions. +=============== +**"License"** shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +**"Licensor"** shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +**"Legal Entity"** shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that +entity. For the purposes of this definition, **"control"** means (i) the power, direct or indirect, to cause the direction or management of such entity, whether +by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +**"You"** (or **"Your"**) shall mean an individual or Legal Entity exercising permissions granted by this License. + +**"Source"** form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and +configuration files. + +**"Object"** form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object +code, generated documentation, and conversions to other media types. + +**"Work"** shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is +included in or attached to the work (an example is provided in the Appendix below). + +**"Derivative Works"** shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, +annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works +shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +**"Contribution"** shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative +Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to +submit on behalf of the copyright owner. For the purposes of this definition, **"submitted"** means any form of electronic, verbal, or written communication +sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue +tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is +conspicuously marked or otherwise designated in writing by the copyright owner as **"Not a Contribution."** + +**"Contributor"** shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently +incorporated within the Work. + +2. Grant of Copyright License. +============================== +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, +irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such +Derivative Works in Source or Object form. + +3. Grant of Patent License. +=========================== +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, +irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such +license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of +their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim +or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then +any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. +================== +You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, +provided that You meet the following conditions: + +* You must give any other recipients of the Work or Derivative Works a copy of this License; and +* You must cause any modified files to carry prominent notices stating that You changed the files; and +* You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source + form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and +* If the Work includes a **"NOTICE"** text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the + attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the + following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the + Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE + file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, + alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or +distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise +complies with the conditions stated in this License. + +5. Submission of Contributions. +=============================== +Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and +conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any +separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. +============== +This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable +and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. +========================== +Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, +MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and +assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. +=========================== +In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate +and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or +consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages +for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been +advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. +============================================== +While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other +liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole +responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability +incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + +---------------------------------------------------------------------------------------------------------------------------------------------------------------- + +**Appendix: How to apply the Apache License to your work** + +To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying +information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or +class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. + +.. code-block:: none + + Copyright [yyyy] [name of copyright owner] + + 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. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/TODO.rst b/doc/TODO.rst new file mode 100644 index 0000000..3144da0 --- /dev/null +++ b/doc/TODO.rst @@ -0,0 +1,4 @@ +TODOs +##### + +.. todolist:: diff --git a/doc/_static/icon.png b/doc/_static/icon.png new file mode 100644 index 0000000..79763da Binary files /dev/null and b/doc/_static/icon.png differ diff --git a/doc/_static/logo.png b/doc/_static/logo.png new file mode 100644 index 0000000..6c62cad Binary files /dev/null and b/doc/_static/logo.png differ diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..d42c29d --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,253 @@ +# 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 importlib.util import find_spec +from sys import path as sys_path +from os.path import abspath +from pathlib import Path +from json import loads + +from pyTooling.Packaging import extractVersionInformation + +ROOT = Path(__file__).resolve().parent + +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) +#sys_path.insert(0, abspath("../pyTooling")) +sys_path.insert(0, abspath("_extensions")) + + +# ============================================================================== +# Project information and versioning +# ============================================================================== +# 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 = "Actions" + +packageInformationFile = Path(f"../{project}/__init__.py") +versionInformation = extractVersionInformation(packageInformationFile) + +author = versionInformation.Author +copyright = versionInformation.Copyright +version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. +release = versionInformation.Version + + +# ============================================================================== +# Miscellaneous settings +# ============================================================================== +# The master toctree document. +master_doc = "index" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + "_build", + "_theme", + "Thumbs.db", + ".DS_Store" +] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "manni" + + +# ============================================================================== +# Restructured Text settings +# ============================================================================== +prologPath = "prolog.inc" +try: + with open(prologPath, "r") as prologFile: + rst_prolog = prologFile.read() +except Exception as ex: + print(f"[ERROR:] While reading '{prologPath}'.") + print(ex) + rst_prolog = "" + + +# ============================================================================== +# Options for HTML output +# ============================================================================== +html_context = {} +ctx = ROOT / "context.json" +if ctx.is_file(): + html_context.update(loads(ctx.open('r').read())) + +if (ROOT / "_theme").is_dir(): + html_theme_path = ["."] + html_theme = "_theme" + html_theme_options = { + "logo_only": True, + "home_breadcrumbs": False, + "vcs_pageview_mode": 'blob', +# "body_max_width": None +# "navigation_depth": 5, + } +elif find_spec("sphinx_rtd_theme") is not None: + html_theme = "sphinx_rtd_theme" + html_theme_options = { + "logo_only": True, + "vcs_pageview_mode": 'blob', +# "navigation_depth": 5, + } +else: + html_theme = "alabaster" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# 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") + +# Output file base name for HTML help builder. +htmlhelp_basename = "ActionsDoc" + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +html_last_updated_fmt = "%d.%m.%Y" + +# ============================================================================== +# Python settings +# ============================================================================== +modindex_common_prefix = [ + f"{project}." +] + +# ============================================================================== +# Options for LaTeX / PDF output +# ============================================================================== +from textwrap import dedent + +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', +} + +# 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, + "Actions.tex", + "The pyTooling Actions Documentation", + "Patrick Lehmann", + "manual" + ), +] + + +# ============================================================================== +# Extensions +# ============================================================================== +extensions = [ +# Standard Sphinx extensions + "sphinx.ext.coverage", + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.graphviz", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", +# SphinxContrib extensions + "sphinxcontrib.mermaid", +# Other extensions + "sphinx_fontawesome", +] + + +# ============================================================================== +# Sphinx.Ext.InterSphinx +# ============================================================================== +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + + +# ============================================================================== +# Sphinx.Ext.AutoDoc +# ============================================================================== +# see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration +#autodoc_default_options = { +# "private-members": True, +# "special-members": True, +# "inherited-members": True, +# "exclude-members": "__weakref__" +#} +#autodoc_class_signature = "separated" +autodoc_member_order = "bysource" # alphabetical, groupwise, bysource +autodoc_typehints = "both" +#autoclass_content = "both" + + +# ============================================================================== +# Sphinx.Ext.ExtLinks +# ============================================================================== +extlinks = { + "gh": ("https://GitHub.com/%s", "gh:"), + "ghissue": ("https://GitHub.com/pyTooling/Actions/issues/%s", "issue #"), + "ghpull": ("https://GitHub.com/pyTooling/Actions/pull/%s", "pull request #"), + "ghsrc": ("https://GitHub.com/pyTooling/Actions/blob/main/%s", ""), + "wiki": ("https://en.wikipedia.org/wiki/%s", ""), +} + + +# ============================================================================== +# Sphinx.Ext.Graphviz +# ============================================================================== +graphviz_output_format = "svg" + + +# ============================================================================== +# SphinxContrib.Mermaid +# ============================================================================== +mermaid_params = [ + '--backgroundColor', 'transparent', +] +mermaid_verbose = True + + +# ============================================================================== +# Sphinx.Ext.ToDo +# ============================================================================== +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True +todo_link_only = True + + +# ============================================================================== +# Sphinx.Ext.Coverage +# ============================================================================== +coverage_show_missing_items = True diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..020e393 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,120 @@ +.. include:: shields.inc + +.. raw:: latex + + \part{Introduction} + +.. only:: html + + | |SHIELD:svg:pyTooling-github| |SHIELD:svg:pyTooling-src-license| |SHIELD:svg:pyTooling-ghp-doc| |SHIELD:svg:pyTooling-doc-license| + | |SHIELD:svg:pyTooling-tag| |SHIELD:svg:pyTooling-date| + +.. Disabled shields: |SHIELD:svg:pyTooling-gitter| + +.. only:: latex + + |SHIELD:png:pyTooling-github| |SHIELD:png:pyTooling-src-license| |SHIELD:png:pyTooling-ghp-doc| |SHIELD:png:pyTooling-doc-license| + |SHIELD:png:pyTooling-tag| |SHIELD:png:pyTooling-date| + +.. Disabled shields: |SHIELD:svg:pyTooling-gitter| + +-------------------------------------------------------------------------------- + +pyTooling Actions Documentation +############################### + +**pyTooling Actions** are reusable steps and workflows for GitHub Actions easing the creation and maintenance of +workflows for Python projects on GitHub. + +GitHub Actions workflows, actions and documentation are mostly focused on JavaScript/TypeScript as the scripting +language for writing reusable CI code. +However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats. +This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation. + +Introduction +************ + + + +Package Details +*************** + + +Contributors +************ + +* `Patrick Lehmann `__ +* `Unai Martinez-Corral `__ (Maintainer) +* `and more... `__ + + +License +******* + +.. only:: html + + This Python package (source code) is licensed under `Apache License 2.0 `__. |br| + The accompanying documentation is licensed under `Creative Commons - Attribution 4.0 (CC-BY 4.0) `__. + +.. only:: latex + + This Python package (source code) is licensed under **Apache License 2.0**. |br| + The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**. + + +------------------------------------ + +.. |docdate| date:: %b %d, %Y - %H:%M + +.. only:: html + + This document was generated on |docdate|. + +.. toctree:: + :caption: Overview + :hidden: + + Introduction + Dependency + +.. raw:: latex + + \part{Main Documentation} + +.. toctree:: + :caption: Job Templates + :hidden: + + JobTemplate/index + JobTemplate/Parameters + JobTemplate/CoverageCollection + JobTemplate/UnitTesting + JobTemplate/StaticTypeCheck + JobTemplate/PublishTestResults + JobTemplate/Package + JobTemplate/PublishOnPyPI + JobTemplate/VerifyDocs + JobTemplate/BuildTheDocs + JobTemplate/PublishToGitHubPages + JobTemplate/Release + JobTemplate/ArtifactCleanUp + +.. toctree:: + :caption: Actions + :hidden: + + Action/index + Action/Releaser + +.. raw:: latex + + \part{Appendix} + +.. toctree:: + :caption: Appendix + :hidden: + + License + Doc-License + genindex + TODO diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..39e6f08 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXOPTS=-v + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/prolog.inc b/doc/prolog.inc new file mode 100644 index 0000000..75463a8 --- /dev/null +++ b/doc/prolog.inc @@ -0,0 +1,59 @@ +.. # Load pre-defined aliases and graphical characters like © from docutils + # is used to denote the special path + # \Lib\site-packages\docutils\parsers\rst\include +.. 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 + +.. role:: pycode(code) + :language: python + :class: highlight diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..1756b55 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,23 @@ +-r ../requirements.txt + +pyTooling>=2.5.0 + +# Enforce latest version on ReadTheDocs +sphinx>=5.3.0 + +# Sphinx Extenstions +#sphinx.ext.coverage +#sphinxcontrib-actdiag>=0.8.5 +sphinxcontrib-mermaid>=0.7.1 +#sphinxcontrib-seqdiag>=0.8.5 +#sphinxcontrib-textstyle>=0.2.1 +#sphinxcontrib-spelling>=2.2.0 +autoapi +sphinx_fontawesome>=0.0.6 +sphinx_autodoc_typehints>=1.19.4 +# changelog>=0.3.5 + +# BuildTheDocs Extensions (mostly patched Sphinx extensions) + +# For pyTooling.Configuration.YAML documentation +ruamel.yaml>=0.17 diff --git a/doc/shields.inc b/doc/shields.inc new file mode 100644 index 0000000..039867c --- /dev/null +++ b/doc/shields.inc @@ -0,0 +1,74 @@ +.. # Use http://b64.io/ to encode any image to base64. Then replace `/` with + # `%2F` and `+` with `%2B` (or use http://meyerweb.com/eric/tools/dencoder/). + # Beware that `?logo=data:image/png;base64,` must also be converted to + # percent encoding so that the URL is properly parsed. + +.. # Sourcecode link to GitHub +.. |SHIELD:svg:pyTooling-github| image:: https://img.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub + :alt: Sourcecode on GitHub + :height: 22 + :target: https://GitHub.com/pyTooling/pyTooling +.. |SHIELD:png:pyTooling-github| image:: https://raster.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub + :alt: Sourcecode on GitHub + :height: 22 + :target: https://GitHub.com/pyTooling/pyTooling + +.. # Sourcecode license +.. |SHIELD:svg:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code + :alt: Code license + :height: 22 + :target: Code-License.html +.. |SHIELD:png:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code + :alt: Code license + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/blob/main/LICENSE.md + +.. # GitHub tag +.. |SHIELD:svg:pyTooling-tag| image:: https://img.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases + :alt: GitHub tag (latest SemVer incl. pre-release + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/tags +.. |SHIELD:png:pyTooling-tag| image:: https://raster.shields.io/github/v/tag/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub&include_prereleases + :alt: GitHub tag (latest SemVer incl. pre-release + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/tags + +.. # GitHub release date +.. |SHIELD:svg:pyTooling-date| image:: https://img.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub + :alt: GitHub release date + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/releases +.. |SHIELD:png:pyTooling-date| image:: https://raster.shields.io/github/release-date/pyTooling/Actions?longCache=true&style=flat-square&logo=GitHub + :alt: GitHub release date + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/releases + +.. # Documentation license +.. |SHIELD:svg:pyTooling-doc-license| image:: https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff + :alt: Documentation License + :height: 22 + :target: License.html +.. |SHIELD:png:pyTooling-doc-license| image:: https://raster.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff + :alt: Documentation License + :height: 22 + :target: https://GitHub.com/pyTooling/Actions/blob/main/doc/License.rst + +.. # GHPages - read now +.. |SHIELD:svg:pyTooling-ghp-doc| image:: https://img.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html + :alt: Documentation - Read Now! + :height: 22 + :target: https://pyTooling.github.io/pyTooling/ +.. |SHIELD:png:pyTooling-ghp-doc| image:: https://raster.shields.io/website?longCache=true&style=flat-square&label=pyTooling.github.io%2FpyTooling&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2FpyTooling.github.io%2FpyTooling%2Findex.html + :alt: Documentation - Read Now! + :height: 22 + :target: https://pyTooling.github.io/pyTooling/ + +.. # Gitter +.. |SHIELD:svg:pyTooling-gitter| image:: https://img.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef + :alt: Documentation License + :height: 22 + :target: https://gitter.im/hdl/community +.. |SHIELD:png:pyTooling-gitter| image:: https://raster.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef + :alt: Documentation License + :height: 22 + :target: https://gitter.im/hdl/community diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e69de29