diff --git a/.github/workflows/build-and-publish.yml b/.github/workflows/build-and-publish.yml index 4813cc73b..f42d877ee 100644 --- a/.github/workflows/build-and-publish.yml +++ b/.github/workflows/build-and-publish.yml @@ -23,7 +23,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/check-release-tag.yml b/.github/workflows/check-release-tag.yml index 2191c3057..0e3971ab1 100644 --- a/.github/workflows/check-release-tag.yml +++ b/.github/workflows/check-release-tag.yml @@ -21,7 +21,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 2c0dc355e..d247a7e29 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -20,7 +20,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" @@ -48,7 +48,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" @@ -75,7 +75,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -113,7 +113,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -141,7 +141,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -173,7 +173,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" @@ -196,7 +196,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" @@ -219,7 +219,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" @@ -242,7 +242,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/dependency-update.yml b/.github/workflows/dependency-update.yml index 62cbc9c53..2945c41ee 100644 --- a/.github/workflows/dependency-update.yml +++ b/.github/workflows/dependency-update.yml @@ -35,7 +35,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/fast-tests.yml b/.github/workflows/fast-tests.yml index ac7faa679..3958495e7 100644 --- a/.github/workflows/fast-tests.yml +++ b/.github/workflows/fast-tests.yml @@ -25,7 +25,7 @@ jobs: fetch-depth: 0 - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 134be7f44..ff05877bf 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -22,7 +22,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/matrix.yml b/.github/workflows/matrix.yml index c0476ae0c..de338684a 100644 --- a/.github/workflows/matrix.yml +++ b/.github/workflows/matrix.yml @@ -28,7 +28,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/.github/workflows/report.yml b/.github/workflows/report.yml index 621a6447d..5df42e9e6 100644 --- a/.github/workflows/report.yml +++ b/.github/workflows/report.yml @@ -24,7 +24,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v9 + uses: exasol/python-toolbox/.github/actions/python-environment@v10 with: python-version: "3.10" poetry-version: "2.3.0" diff --git a/doc/_includes/nox_sessions_catalog.rst b/doc/_includes/nox_sessions_catalog.rst new file mode 100644 index 000000000..c6db24ac2 --- /dev/null +++ b/doc/_includes/nox_sessions_catalog.rst @@ -0,0 +1,121 @@ +Common PTB Nox Sessions +^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 24 48 28 + :header-rows: 1 + + * - Session + - Purpose + - More information + * - ``format:fix`` + - Apply automated formatting and cleanup fixes. + - :ref:`formatting_code` + * - ``format:check`` + - Verify formatting without changing files. + - :ref:`formatting_code` + * - ``project:check`` + - Run the main local quality gate across formatting, linting, typing, and coverage. + - :ref:`features` + * - ``lint:code`` + - Run ``pylint`` and write ``.lint.json``. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``lint:typing`` + - Run ``mypy`` over the project. + - :ref:`features` + * - ``lint:security`` + - Run ``bandit`` and write ``.security.json``. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``lint:dependencies`` + - Reject git, path, and URL-based Poetry dependencies. + - :ref:`managing_dependencies` + * - ``lint:import`` + - Run Import Linter against ``.import_linter_config``. + - `Import Linter docs `_ + * - ``test:unit`` + - Run unit tests. + - :ref:`features` + * - ``test:integration`` + - Run integration tests, including plugin hooks when configured. + - :ref:`plugins` + * - ``test:coverage`` + - Run unit and integration tests and print a combined coverage report. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``docs:build`` + - Build the documentation with Sphinx. + - :ref:`deploying_documentation` + * - ``docs:multiversion`` + - Build multiversion documentation output. + - :ref:`deploying_documentation` + * - ``docs:open`` + - Open the built documentation locally. + - :ref:`deploying_documentation` + * - ``docs:clean`` + - Remove built documentation output. + - :ref:`deploying_documentation` + * - ``links:list`` + - List documentation links discovered by Sphinx linkcheck. + - :ref:`deploying_documentation` + * - ``links:check`` + - Validate documentation links. + - :ref:`deploying_documentation` + * - ``changelog:updated`` + - Fail if ``doc/changes`` was not updated. + - :ref:`deploying_documentation` + * - ``workflow:generate`` + - Render PTB workflow templates into ``.github/workflows``. + - :ref:`GitHub Workflows` + * - ``workflow:check`` + - Compare checked-in workflows to generated PTB output. + - :ref:`GitHub Workflows` + * - ``workflow:audit`` + - Run ``zizmor`` against workflows and actions. + - :ref:`managing_dependencies` + * - ``matrix:generate`` + - Emit selected ``BaseConfig`` values as JSON for workflow matrices. + - :ref:`GitHub Workflows` + * - ``matrix:python`` + - Deprecated Python-only matrix output. + - :ref:`GitHub Workflows` + * - ``matrix:exasol`` + - Deprecated Exasol-only matrix output. + - :ref:`GitHub Workflows` + * - ``matrix:all`` + - Deprecated combined matrix output. + - :ref:`GitHub Workflows` + * - ``artifacts:copy`` + - Combine coverage artifacts and copy report inputs into the project root. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``artifacts:validate`` + - Validate ``.lint.json``, ``.security.json``, and ``.coverage`` before Sonar upload. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``sonar:check`` + - Generate ``ci-coverage.xml`` and upload code-quality data to Sonar. + - :doc:`/user_guide/features/metrics/collecting_metrics` + * - ``dependency:licenses`` + - Print dependency license information. + - :ref:`managing_dependencies` + * - ``dependency:audit`` + - Report known dependency vulnerabilities with ``pip-audit``. + - :ref:`managing_dependencies` + * - ``vulnerabilities:resolved`` + - Report vulnerabilities resolved since the last release. + - :ref:`managing_dependencies` + * - ``package:check`` + - Build the package and verify the long description with ``twine check``. + - :ref:`features` + * - ``release:prepare`` + - Bump the version, prepare changelog files, create a release branch, and optionally open a pull request. + - :doc:`/user_guide/features/creating_a_release` + * - ``release:update`` + - Refresh the prepared release changelog. + - :doc:`/user_guide/features/creating_a_release` + * - ``release:trigger`` + - Create and push the release tag. + - :doc:`/user_guide/features/creating_a_release` + +Notes ++++++ + +* The old task name ``test:typing`` is obsolete. The current session name is ``lint:typing``. +* The ``matrix:python``, ``matrix:exasol``, and ``matrix:all`` sessions are deprecated. Prefer ``matrix:generate``. diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index fb4737052..4c529d1c1 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -1,3 +1,10 @@ # Unreleased ## Summary + +Documented the common PTB Nox sessions in the user guide and removed the unused +developer-guide Modules section. + +## Documentation + +* #456: Cataloged common PTB nox sessions in the user guide and removed the unused developer-guide Modules section diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst index cc9224315..03037fd33 100644 --- a/doc/developer_guide/developer_guide.rst +++ b/doc/developer_guide/developer_guide.rst @@ -9,4 +9,3 @@ ../design plugins - modules/modules diff --git a/doc/developer_guide/modules/modules.rst b/doc/developer_guide/modules/modules.rst deleted file mode 100644 index 21c47bf28..000000000 --- a/doc/developer_guide/modules/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -Modules -======= - -.. toctree:: - :maxdepth: 2 - - nox_tasks diff --git a/doc/developer_guide/modules/nox_tasks.rst b/doc/developer_guide/modules/nox_tasks.rst deleted file mode 100644 index b930c8d75..000000000 --- a/doc/developer_guide/modules/nox_tasks.rst +++ /dev/null @@ -1,14 +0,0 @@ -nox_tasks -========= - -lint:import (experimental) -__________________________ - -`Import Linter `_ -allows you to define and enforce rules for the imports within and between Python packages. - -.. important:: - - First configure the linter in file :code:`.import_linter_config`, see - `import-linter top-level-configuration `_ - and `import-linter contract types `_ diff --git a/doc/user_guide/features/index.rst b/doc/user_guide/features/index.rst index 373fb643b..e773ad305 100644 --- a/doc/user_guide/features/index.rst +++ b/doc/user_guide/features/index.rst @@ -37,3 +37,9 @@ Important Nox Commands * :code:`nox -l` shows a list of all available nox sessions * :code:`nox -s ` run the specified session(s) + +The most commonly used PTB sessions are cataloged below. The links in the +right-hand column point to the feature pages that explain the user-facing +workflow behind each session. + +.. include:: ../../_includes/nox_sessions_catalog.rst