[stable-2.15] Backport workflow automation (#342)

Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Don Naro <dnaro@redhat.com>

.github/dependabot.yml

@@ -0,0 +1,11 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yaml

@@ -4,7 +4,9 @@ on:
   push:
     branches-ignore:
       - 'patchback/**'
+      - 'pip-compile/**'
   pull_request:
+  workflow_dispatch:
 
 jobs:
   docs_sanity_docs_build:
@@ -54,3 +56,6 @@ jobs:
     - name: Run rstcheck Sanity
       run: |
         python tests/sanity.py rstcheck
+
+  nox:
+    uses: ./.github/workflows/reusable-nox.yml

.github/workflows/reusable-nox.yml

@@ -0,0 +1,30 @@
+---
+name: nox
+
+"on":
+  workflow_call:
+
+jobs:
+  nox:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - session: static
+            python-versions: "3.11"
+          - session: formatters_check
+            python-versions: "3.11"
+          - session: typing
+            python-versions: "3.11"
+    name: "Run nox ${{ matrix.session }} session"
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v3
+      - name: Setup nox
+        uses: wntrblm/nox@2023.04.22
+        with:
+          python-versions: "${{ matrix.python-versions }}"
+      - name: "Run nox -e ${{ matrix.session }}"
+        run: |
+          nox -e "${{ matrix.session }}"

.isort.cfg

@@ -0,0 +1,2 @@
+[isort]
+profile = black

.pip-tools.toml

@@ -0,0 +1,5 @@
+[tool.pip-tools]
+resolver = "backtracking"
+allow-unsafe = true
+strip-extras = true
+quiet = true

docs/docsite/rst/community/documentation_contributions.rst

@@ -111,6 +111,7 @@ Drop the ``--user`` option in the following commands if you use a virtual enviro
 
     pip install --user -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions.
     pip install --user -r tests/requirements.in # Installs the unpinned dependency versions.
+    pip install --user -r tests/requirements-relaxed.in # Installs the unpinned dependency versions including untested antsibull-docs.
 
 .. note::
 

noxfile.py

@@ -0,0 +1,77 @@
+import os
+from pathlib import Path
+
+import nox
+
+LINT_FILES = ("hacking/pr_labeler/label.py", "noxfile.py")
+PINNED = os.environ.get("PINNED", "true").lower() in {"1", "true"}
+nox.options.sessions = ("lint",)
+
+
+def install(session: nox.Session, *args, req: str, **kwargs):
+    if PINNED:
+        kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = f"tests/{req}.txt"
+    session.install("-r", f"tests/{req}.in", *args, **kwargs)
+
+
+@nox.session
+def static(session: nox.Session):
+    """
+    Run static checkers
+    """
+    install(session, req="static")
+    session.run("ruff", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def formatters(session: nox.Session):
+    """
+    Reformat code
+    """
+    install(session, req="formatters")
+    session.run("isort", *session.posargs, *LINT_FILES)
+    session.run("black", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def formatters_check(session: nox.Session):
+    """
+    Check code formatting without making changes
+    """
+    install(session, req="formatters")
+    session.run("isort", "--check", *session.posargs, *LINT_FILES)
+    session.run("black", "--check", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def typing(session: nox.Session):
+    install(session, req="typing")
+    session.run("mypy", *session.posargs, *LINT_FILES)
+
+
+@nox.session
+def lint(session: nox.Session):
+    session.notify("typing")
+    session.notify("static")
+    session.notify("formatters")
+
+
+requirements_files = list(
+    {path.name.replace(".in", "") for path in Path("tests").glob("*in")}
+    - {"constraints", "constraints-base"}
+)
+
+
+@nox.session(name="pip-compile", python=["3.10"])
+@nox.parametrize(["req"], requirements_files, requirements_files)
+def pip_compile(session: nox.Session, req: str):
+    # .pip-tools.toml was introduced in v7
+    session.install("pip-tools >= 7")
+    # fmt: off
+    session.run(
+        "pip-compile",
+        "--upgrade",
+        "--output-file", f"tests/{req}.txt",
+        f"tests/{req}.in",
+    )
+    # fmt: on

tests/constraints-base.in

@@ -0,0 +1,4 @@
+# Known limitations for indirect/transitive dependencies.
+
+rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
+sphinx < 7.2.0 # https://github.com/readthedocs/sphinx-notfound-page/issues/219

tests/constraints.in

@@ -1,5 +1,5 @@
-# Known limitations for indirect/transitive dependencies.
-resolvelib < 1.1.0
+# This constraints file contains pins for the stable, tested versions of sphinx
+# and antsibull-docs that production builds rely upon.
+
 sphinx == 5.3.0
-rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
 antsibull-docs == 2.3.1  # currently approved version

tests/formatters.in

@@ -0,0 +1,2 @@
+black
+isort

tests/formatters.txt

@@ -0,0 +1,22 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in
+#
+black==23.7.0
+    # via -r tests/formatters.in
+click==8.1.7
+    # via black
+isort==5.12.0
+    # via -r tests/formatters.in
+mypy-extensions==1.0.0
+    # via black
+packaging==23.1
+    # via black
+pathspec==0.11.2
+    # via black
+platformdirs==3.10.0
+    # via black
+tomli==2.0.1
+    # via black

tests/requirements-relaxed.in

@@ -0,0 +1,14 @@
+# This requirements file contains no pins on antsibull-docs and other
+# essential tools
+# It's used for testing purposes and devel branch builds on docs.ansible.com.
+
+-c constraints-base.in
+
+jinja2 >= 3.0.0 # used by hacking/build_library/build_ansible/command_plugins/generate_man.py and dump_keywords.py
+pyyaml >= 5.1 # used by ansible-core
+resolvelib >= 0.5.3, < 1.1.0 # used by ansible-core
+sphinx
+sphinx-notfound-page
+sphinx-ansible-theme
+rstcheck
+antsibull-docs ~= 2.0

tests/requirements-relaxed.txt

@@ -0,0 +1,163 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=tests/requirements-relaxed.txt --strip-extras tests/requirements-relaxed.in
+#
+aiofiles==23.2.1
+    # via antsibull-core
+aiohttp==3.8.5
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+aiosignal==1.3.1
+    # via aiohttp
+alabaster==0.7.13
+    # via sphinx
+ansible-pygments==0.1.1
+    # via
+    #   antsibull-docs
+    #   sphinx-ansible-theme
+antsibull-core==2.0.0
+    # via antsibull-docs
+antsibull-docs==2.3.1
+    # via -r tests/requirements-relaxed.in
+antsibull-docs-parser==1.0.0
+    # via antsibull-docs
+async-timeout==4.0.3
+    # via aiohttp
+asyncio-pool==0.6.0
+    # via antsibull-docs
+attrs==23.1.0
+    # via aiohttp
+babel==2.12.1
+    # via sphinx
+build==0.10.0
+    # via antsibull-core
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.2.0
+    # via
+    #   aiohttp
+    #   requests
+docutils==0.18.1
+    # via
+    #   antsibull-docs
+    #   rstcheck
+    #   sphinx
+    #   sphinx-rtd-theme
+frozenlist==1.4.0
+    # via
+    #   aiohttp
+    #   aiosignal
+idna==3.4
+    # via
+    #   requests
+    #   yarl
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   -r tests/requirements-relaxed.in
+    #   antsibull-docs
+    #   sphinx
+markupsafe==2.1.3
+    # via jinja2
+multidict==6.0.4
+    # via
+    #   aiohttp
+    #   yarl
+packaging==23.1
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+    #   build
+    #   sphinx
+perky==0.9.2
+    # via antsibull-core
+pydantic==1.10.12
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+pygments==2.16.1
+    # via
+    #   ansible-pygments
+    #   sphinx
+pyproject-hooks==1.0.0
+    # via build
+pyyaml==6.0.1
+    # via
+    #   -r tests/requirements-relaxed.in
+    #   antsibull-core
+    #   antsibull-docs
+requests==2.31.0
+    # via sphinx
+resolvelib==1.0.1
+    # via -r tests/requirements-relaxed.in
+rstcheck==5.0.0
+    # via
+    #   -c tests/constraints-base.in
+    #   -r tests/requirements-relaxed.in
+    #   antsibull-docs
+semantic-version==2.10.0
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+sh==1.14.3
+    # via antsibull-core
+six==1.16.0
+    # via twiggy
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.1.2
+    # via
+    #   -c tests/constraints-base.in
+    #   -r tests/requirements-relaxed.in
+    #   antsibull-docs
+    #   sphinx-ansible-theme
+    #   sphinx-notfound-page
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-ansible-theme==0.10.2
+    # via -r tests/requirements-relaxed.in
+sphinx-notfound-page==0.8.3
+    # via -r tests/requirements-relaxed.in
+sphinx-rtd-theme==1.3.0
+    # via sphinx-ansible-theme
+sphinxcontrib-applehelp==1.0.7
+    # via sphinx
+sphinxcontrib-devhelp==1.0.5
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.4
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.6
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.9
+    # via sphinx
+tomli==2.0.1
+    # via
+    #   build
+    #   pyproject-hooks
+twiggy==0.5.1
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+types-docutils==0.18.3
+    # via rstcheck
+typing-extensions==4.7.1
+    # via
+    #   pydantic
+    #   rstcheck
+urllib3==2.0.4
+    # via requests
+yarl==1.9.2
+    # via aiohttp

tests/requirements.in

@@ -1,10 +1,5 @@
--c constraints.in # <-- contains known limitations
+# This requirements file is used for stable ansible docs builds
+# It depends on specific, tested antsibull-docs and sphinx versions
 
-jinja2 >= 3.0.0 # used by hacking/build_library/build_ansible/command_plugins/generate_man.py and dump_keywords.py
-pyyaml >= 5.1 # used by ansible-core
-resolvelib # used by ansible-core
-sphinx
-sphinx-notfound-page
-sphinx-ansible-theme
-rstcheck
-antsibull-docs
+-c constraints.in # <-- contains known limitations
+-r requirements-relaxed.in # <-- contains base set of dependencies

tests/static.in

@@ -0,0 +1 @@
+ruff

tests/static.txt

@@ -0,0 +1,8 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in
+#
+ruff==0.0.286
+    # via -r tests/static.in

tests/typing.in

@@ -0,0 +1,3 @@
+-r ../hacking/pr_labeler/requirements.txt
+mypy
+nox

tests/typing.txt

@@ -0,0 +1,67 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in
+#
+argcomplete==3.1.1
+    # via nox
+certifi==2023.7.22
+    # via requests
+cffi==1.15.1
+    # via
+    #   cryptography
+    #   pynacl
+charset-normalizer==3.2.0
+    # via requests
+click==8.1.7
+    # via typer
+codeowners==0.6.0
+    # via -r tests/../hacking/pr_labeler/requirements.txt
+colorlog==6.7.0
+    # via nox
+cryptography==41.0.3
+    # via pyjwt
+deprecated==1.2.14
+    # via pygithub
+distlib==0.3.7
+    # via virtualenv
+filelock==3.12.2
+    # via virtualenv
+idna==3.4
+    # via requests
+mypy==1.5.1
+    # via -r tests/typing.in
+mypy-extensions==1.0.0
+    # via mypy
+nox==2023.4.22
+    # via -r tests/typing.in
+packaging==23.1
+    # via nox
+platformdirs==3.10.0
+    # via virtualenv
+pycparser==2.21
+    # via cffi
+pygithub==1.59.1
+    # via -r tests/../hacking/pr_labeler/requirements.txt
+pyjwt==2.8.0
+    # via pygithub
+pynacl==1.5.0
+    # via pygithub
+requests==2.31.0
+    # via pygithub
+tomli==2.0.1
+    # via mypy
+typer==0.9.0
+    # via -r tests/../hacking/pr_labeler/requirements.txt
+typing-extensions==4.7.1
+    # via
+    #   codeowners
+    #   mypy
+    #   typer
+urllib3==2.0.4
+    # via requests
+virtualenv==20.24.3
+    # via nox
+wrapt==1.15.0
+    # via deprecated