antsibull-nox 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

antsibull_nox/data/rst-yamllint.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2025, Felix Fontein <felix@fontein.de>
+# 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
+
+"""Make sure all plugin and module documentation adheres to yamllint."""
+
+from __future__ import annotations
+
+import io
+import os
+import sys
+import traceback
+import typing as t
+
+from antsibull_docutils.rst_code_finder import find_code_blocks
+from antsibull_nox_data_util import setup  # type: ignore
+from yamllint import linter
+from yamllint.config import YamlLintConfig
+from yamllint.linter import PROBLEM_LEVELS
+
+REPORT_LEVELS: set[PROBLEM_LEVELS] = {
+    "warning",
+    "error",
+}
+
+YAML_LANGUAGES = {"yaml", "yaml+jinja"}
+
+
+def lint(
+    *,
+    errors: list[dict[str, t.Any]],
+    path: str,
+    data: str,
+    row_offset: int,
+    col_offset: int,
+    config: YamlLintConfig,
+    extra_for_errors: dict[str, t.Any] | None = None,
+) -> None:
+    # If the string start with optional whitespace + linebreak, skip that line
+    idx = data.find("\n")
+    if idx >= 0 and (idx == 0 or data[:idx].isspace()):
+        data = data[idx + 1 :]
+        row_offset += 1
+        col_offset = 0
+
+    try:
+        problems = linter.run(
+            io.StringIO(data),
+            config,
+            path,
+        )
+        for problem in problems:
+            if problem.level not in REPORT_LEVELS:
+                continue
+            msg = f"{problem.level}: {problem.desc}"
+            if problem.rule:
+                msg += f"  ({problem.rule})"
+            errors.append(
+                {
+                    "path": path,
+                    "line": row_offset + problem.line,
+                    # The col_offset is only valid for line 1; otherwise the offset is 0
+                    "col": (col_offset if problem.line == 1 else 0) + problem.column,
+                    "message": msg,
+                }
+            )
+            if extra_for_errors:
+                errors[-1].update(extra_for_errors)
+    except Exception as exc:
+        error = str(exc).replace("\n", " / ")
+        errors.append(
+            {
+                "path": path,
+                "line": row_offset + 1,
+                "col": col_offset + 1,
+                "message": (
+                    f"Internal error while linting YAML: exception {type(exc)}:"
+                    f" {error}; traceback: {traceback.format_exc()!r}"
+                ),
+            }
+        )
+        if extra_for_errors:
+            errors[-1].update(extra_for_errors)
+
+
+def process_rst_file(
+    errors: list[dict[str, t.Any]],
+    path: str,
+    config: YamlLintConfig,
+) -> None:
+    try:
+        with open(path, "rt", encoding="utf-8") as f:
+            content = f.read()
+    except Exception as exc:
+        errors.append(
+            {
+                "path": path,
+                "line": 1,
+                "col": 1,
+                "message": (
+                    f"Error while reading content: {type(exc)}:"
+                    f" {exc}; traceback: {traceback.format_exc()!r}"
+                ),
+            }
+        )
+        return
+
+    def warn_unknown_block(line: int | str, col: int, content: str) -> None:
+        errors.append(
+            {
+                "path": path,
+                "line": line,
+                "col": col,
+                "message": (
+                    "Warning: found unknown literal block! Check for double colons '::'."
+                    " If that is not the cause, please report this warning."
+                    " It might indicate a bug in the checker or an unsupported Sphinx directive."
+                    f" Content: {content!r}"
+                ),
+            }
+        )
+
+    for code_block in find_code_blocks(
+        content,
+        path=path,
+        root_prefix="docs/docsite/rst",
+        warn_unknown_block=warn_unknown_block,
+    ):
+        if (code_block.language or "").lower() not in YAML_LANGUAGES:
+            continue
+
+        extra_for_errors = {}
+        if not code_block.position_exact:
+            extra_for_errors["note"] = (
+                "The code block could not be exactly located in the source file."
+                " The line/column numbers might be off."
+            )
+
+        # Parse the (remaining) string content
+        lint(
+            errors=errors,
+            path=path,
+            data=code_block.content,
+            row_offset=code_block.row_offset,
+            col_offset=code_block.col_offset,
+            config=config,
+            extra_for_errors=extra_for_errors,
+        )
+
+
+def main() -> int:
+    """Main entry point."""
+    paths, extra_data = setup()
+    config: str | None = extra_data.get("config")
+
+    if config:
+        yamllint_config = YamlLintConfig(file=config)
+    else:
+        yamllint_config = YamlLintConfig(content="extends: default")
+
+    errors: list[dict[str, t.Any]] = []
+    for path in paths:
+        if not os.path.isfile(path):
+            continue
+        process_rst_file(errors, path, yamllint_config)
+
+    errors.sort(
+        key=lambda error: (
+            error["path"],
+            error["line"] if isinstance(error["line"], int) else 0,
+            error["col"],
+            error["message"],
+        )
+    )
+    for error in errors:
+        prefix = f"{error['path']}:{error['line']}:{error['col']}: "
+        msg = error["message"]
+        if "note" in error:
+            msg = f"{msg}\nNote: {error['note']}"
+        for i, line in enumerate(msg.splitlines()):
+            print(f"{prefix}{line}")
+            if i == 0:
+                prefix = " " * len(prefix)
+
+    return len(errors) > 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/interpret_config.py

@@ -111,6 +111,22 @@ def _add_sessions(sessions: Sessions) -> None:
             run_black_modules=sessions.lint.run_black_modules,
             black_config=sessions.lint.black_config,
             black_package=sessions.lint.black_package,
+            run_ruff_format=sessions.lint.run_ruff_format,
+            ruff_format_config=sessions.lint.ruff_format_config
+            or sessions.lint.ruff_config,
+            ruff_format_package=sessions.lint.ruff_format_package
+            or sessions.lint.ruff_package,
+            run_ruff_autofix=sessions.lint.run_ruff_autofix,
+            ruff_autofix_config=sessions.lint.ruff_autofix_config
+            or sessions.lint.ruff_config,
+            ruff_autofix_package=sessions.lint.ruff_autofix_package
+            or sessions.lint.ruff_package,
+            ruff_autofix_select=sessions.lint.ruff_autofix_select,
+            run_ruff_check=sessions.lint.run_ruff_check,
+            ruff_check_config=sessions.lint.ruff_check_config
+            or sessions.lint.ruff_config,
+            ruff_check_package=sessions.lint.ruff_check_package
+            or sessions.lint.ruff_package,
             run_flake8=sessions.lint.run_flake8,
             flake8_config=sessions.lint.flake8_config,
             flake8_package=sessions.lint.flake8_package,
@@ -124,7 +140,9 @@ def _add_sessions(sessions: Sessions) -> None:
             yamllint_config=sessions.lint.yamllint_config,
             yamllint_config_plugins=sessions.lint.yamllint_config_plugins,
             yamllint_config_plugins_examples=sessions.lint.yamllint_config_plugins_examples,
+            yamllint_config_extra_docs=sessions.lint.yamllint_config_extra_docs,
             yamllint_package=sessions.lint.yamllint_package,
+            yamllint_antsibull_docutils_package=sessions.lint.yamllint_antsibull_docutils_package,
             run_mypy=sessions.lint.run_mypy,
             mypy_config=sessions.lint.mypy_config,
             mypy_package=sessions.lint.mypy_package,
@@ -139,6 +157,13 @@ def _add_sessions(sessions: Sessions) -> None:
             ansible_core_package=sessions.docs_check.ansible_core_package,
             validate_collection_refs=sessions.docs_check.validate_collection_refs,
             extra_collections=sessions.docs_check.extra_collections,
+            codeblocks_restrict_types=sessions.docs_check.codeblocks_restrict_types,
+            codeblocks_restrict_type_exact_case=(
+                sessions.docs_check.codeblocks_restrict_type_exact_case
+            ),
+            codeblocks_allow_without_type=sessions.docs_check.codeblocks_allow_without_type,
+            codeblocks_allow_literal_blocks=sessions.docs_check.codeblocks_allow_literal_blocks,
+            antsibull_docutils_package=sessions.docs_check.antsibull_docutils_package,
         )
     if sessions.license_check:
         add_license_check(
@@ -179,6 +204,13 @@ def _add_sessions(sessions: Sessions) -> None:
             action_groups_config=_convert_action_groups(
                 sessions.extra_checks.action_groups_config
             ),
+            run_no_trailing_whitespace=sessions.extra_checks.run_no_trailing_whitespace,
+            no_trailing_whitespace_skip_paths=(
+                sessions.extra_checks.no_trailing_whitespace_skip_paths
+            ),
+            no_trailing_whitespace_skip_directories=(
+                sessions.extra_checks.no_trailing_whitespace_skip_directories
+            ),
         )
     if sessions.build_import_check:
         add_build_import_check(
@@ -238,6 +270,7 @@ def _add_sessions(sessions: Sessions) -> None:
                 cfg.core_python_versions
             ),
             controller_python_versions_only=cfg.controller_python_versions_only,
+            ansible_vars_from_env_vars=cfg.ansible_vars_from_env_vars,
         )
     if sessions.ansible_lint:
         add_ansible_lint(

antsibull_nox/paths.py

@@ -14,10 +14,10 @@ import atexit
 import functools
 import os
 import shutil
-import tempfile
 from pathlib import Path
 
 from antsibull_fileutils.copier import Copier, GitCopier
+from antsibull_fileutils.tempfile import ansible_mkdtemp
 from antsibull_fileutils.vcs import detect_vcs, list_git_files
 
 
@@ -181,8 +181,7 @@ def create_temp_directory(basename: str) -> Path:
     """
     Create a temporary directory outside the nox tree.
     """
-    directory = tempfile.mkdtemp(prefix=basename)
-    path = Path(directory)
+    path = ansible_mkdtemp(prefix=basename)
 
     def cleanup() -> None:
         remove_path(path)

antsibull_nox/sessions/ansible_test.py

@@ -16,6 +16,7 @@ from collections.abc import Callable
 from pathlib import Path
 
 import nox
+from antsibull_fileutils.yaml import store_yaml_file
 
 from ..ansible import (
     AnsibleCoreVersion,
@@ -168,7 +169,7 @@ def add_ansible_test_sanity_test_session(
     """
     Add generic ansible-test sanity test session.
     """
-    command = ["sanity", "--docker", "-v", "--color"]
+    command = ["sanity", "--color", "-v", "--docker"]
     if skip_tests:
         for test in skip_tests:
             command.extend(["--skip", test])
@@ -302,7 +303,7 @@ def add_ansible_test_unit_test_session(
     add_ansible_test_session(
         name=name,
         description=description,
-        ansible_test_params=["units", "--docker", "-v", "--color"],
+        ansible_test_params=["units", "--color", "-v", "--docker"],
         extra_deps_files=["tests/unit/requirements.yml"],
         default=default,
         ansible_core_version=ansible_core_version,
@@ -397,6 +398,7 @@ def add_ansible_test_integration_sessions_default_container(
         dict[str | AnsibleCoreVersion, list[str | Version]] | None
     ) = None,
     controller_python_versions_only: bool = False,
+    ansible_vars_from_env_vars: dict[str, str] | None = None,
     default: bool = False,
 ) -> None:
     """
@@ -409,6 +411,18 @@ def add_ansible_test_integration_sessions_default_container(
     controller Python versions.
     """
 
+    def callback_before() -> None:
+        if not ansible_vars_from_env_vars:
+            return
+
+        path = Path("tests", "integration", "integration_config.yml")
+        content: dict[str, t.Any] = {}
+        for ans_var, env_var in ansible_vars_from_env_vars.items():
+            value = os.environ.get(env_var)
+            if value is not None:
+                content[ans_var] = env_var
+        store_yaml_file(path, content, nice=True, sort_keys=True)
+
     def add_integration_tests(
         ansible_core_version: AnsibleCoreVersion,
         repo_name: str | None = None,
@@ -459,10 +473,10 @@ def add_ansible_test_integration_sessions_default_container(
                 description=description,
                 ansible_test_params=[
                     "integration",
+                    "--color",
+                    "-v",
                     "--docker",
                     "default",
-                    "-v",
-                    "--color",
                     "--python",
                     str(py_version),
                 ],
@@ -470,6 +484,7 @@ def add_ansible_test_integration_sessions_default_container(
                 ansible_core_version=ansible_core_version,
                 ansible_core_repo_name=repo_name,
                 ansible_core_branch_name=branch_name,
+                callback_before=callback_before,
                 default=False,
                 register_name="integration",
                 register_extra_data={

antsibull_nox/sessions/build_import_check.py

@@ -17,12 +17,7 @@ from pathlib import Path
 import nox
 
 from ..collection import (
-    force_collection_version,
-    load_collection_data_from_disk,
-)
-from ..paths import (
-    copy_collection,
-    remove_path,
+    build_collection,
 )
 from .utils import (
     ci_group,
@@ -57,41 +52,16 @@ def add_build_import_check(
     def build_import_check(session: nox.Session) -> None:
         install(session, *compose_dependencies())
 
-        tmp = Path(session.create_tmp())
-        collection_dir = tmp / "collection"
-        remove_path(collection_dir)
-        copy_collection(Path.cwd(), collection_dir)
-
-        collection = load_collection_data_from_disk(
-            collection_dir, accept_manifest=False
-        )
-        version = collection.version
-        if not version:
-            version = "0.0.1"
-            force_collection_version(collection_dir, version=version)
-
-        with session.chdir(collection_dir):
-            build_ran = session.run("ansible-galaxy", "collection", "build") is not None
-
-        tarball = (
-            collection_dir
-            / f"{collection.namespace}-{collection.name}-{version}.tar.gz"
-        )
-        if build_ran and not tarball.is_file():
-            files = "\n".join(
-                f"* {path.name}"
-                for path in collection_dir.iterdir()
-                if not path.is_dir()
-            )
-            session.error(f"Cannot find file {tarball}! List of all files:\n{files}")
+        tarball, _, __ = build_collection(session)
 
-        if run_galaxy_importer and tarball.is_file():
+        if run_galaxy_importer and tarball:
             env = {}
             if galaxy_importer_config_path:
                 env["GALAXY_IMPORTER_CONFIG"] = str(
                     Path(galaxy_importer_config_path).absolute()
                 )
-            with session.chdir(collection_dir), silence_run_verbosity():
+            assert tarball.parent is not None
+            with session.chdir(tarball.parent), silence_run_verbosity():
                 import_log = session.run(
                     "python",
                     "-m",

antsibull_nox/sessions/docs_check.py

@@ -11,14 +11,35 @@ Create nox docs check session.
 from __future__ import annotations
 
 import typing as t
+from pathlib import Path
 
 import nox
 
+from ..paths import (
+    list_all_files,
+)
 from .collections import (
     CollectionSetup,
     prepare_collections,
 )
-from .utils import install
+from .utils import (
+    install,
+    run_bare_script,
+)
+
+
+def find_extra_docs_rst_files() -> list[Path]:
+    """
+    Find all RST extra document files.
+    """
+    all_files = list_all_files()
+    cwd = Path.cwd()
+    extra_docs_dir = cwd / "docs" / "docsite" / "rst"
+    return [
+        file
+        for file in all_files
+        if file.is_relative_to(extra_docs_dir) and file.name.lower().endswith((".rst"))
+    ]
 
 
 def add_docs_check(
@@ -28,15 +49,47 @@ def add_docs_check(
     ansible_core_package: str = "ansible-core",
     validate_collection_refs: t.Literal["self", "dependent", "all"] | None = None,
     extra_collections: list[str] | None = None,
+    codeblocks_restrict_types: list[str] | None = None,
+    codeblocks_restrict_type_exact_case: bool = True,
+    codeblocks_allow_without_type: bool = True,
+    codeblocks_allow_literal_blocks: bool = True,
+    antsibull_docutils_package: str = "antsibull-docutils",
 ) -> None:
     """
     Add docs-check session for linting.
     """
+    run_extra_checks = (
+        codeblocks_restrict_types is not None
+        or not codeblocks_allow_without_type
+        or not codeblocks_allow_literal_blocks
+    )
 
     def compose_dependencies() -> list[str]:
         deps = [antsibull_docs_package, ansible_core_package]
+        if run_extra_checks:
+            deps.append(antsibull_docutils_package)
         return deps
 
+    def execute_extra_checks(session: nox.Session) -> None:
+        all_extra_docs = find_extra_docs_rst_files()
+        if not all_extra_docs:
+            session.warn(
+                "Skipping codeblock checks since no appropriate RST file was found..."
+            )
+            return
+        run_bare_script(
+            session,
+            "rst-extra",
+            use_session_python=True,
+            files=all_extra_docs,
+            extra_data={
+                "codeblocks_restrict_types": codeblocks_restrict_types,
+                "codeblocks_restrict_type_exact_case": codeblocks_restrict_type_exact_case,
+                "codeblocks_allow_without_type": codeblocks_allow_without_type,
+                "codeblocks_allow_literal_blocks": codeblocks_allow_literal_blocks,
+            },
+        )
+
     def execute_antsibull_docs(
         session: nox.Session, prepared_collections: CollectionSetup
     ) -> None:
@@ -61,6 +114,8 @@ def add_docs_check(
             extra_collections=extra_collections,
             install_out_of_tree=True,
         )
+        if run_extra_checks:
+            execute_extra_checks(session)
         if not prepared_collections:
             session.warn("Skipping antsibull-docs...")
         if prepared_collections:

antsibull_nox/sessions/extra_checks.py

@@ -58,6 +58,10 @@ def add_extra_checks(
     # action-groups:
     run_action_groups: bool = False,
     action_groups_config: list[ActionGroup] | None = None,
+    # no-trailing-whitespace:
+    run_no_trailing_whitespace: bool = False,
+    no_trailing_whitespace_skip_paths: list[str] | None = None,
+    no_trailing_whitespace_skip_directories: list[str] | None = None,
 ) -> None:
     """
     Add extra-checks session for extra checks.
@@ -94,11 +98,23 @@ def add_extra_checks(
             },
         )
 
+    def execute_no_trailing_whitespace(session: nox.Session) -> None:
+        run_bare_script(
+            session,
+            "no-trailing-whitespace",
+            extra_data={
+                "skip_paths": no_trailing_whitespace_skip_paths or [],
+                "skip_directories": no_trailing_whitespace_skip_directories or [],
+            },
+        )
+
     def extra_checks(session: nox.Session) -> None:
         if run_no_unwanted_files:
             execute_no_unwanted_files(session)
         if run_action_groups:
             execute_action_groups(session)
+        if run_no_trailing_whitespace:
+            execute_no_trailing_whitespace(session)
 
     extra_checks.__doc__ = compose_description(
         prefix={
@@ -112,6 +128,9 @@ def add_extra_checks(
                 else False
             ),
             "action-groups": "validate action groups" if run_action_groups else False,
+            "no-trailing-whitespace": (
+                "avoid trailing whitespace" if run_no_trailing_whitespace else False
+            ),
         },
     )
     nox.session(