path: root/scripts/sphinx-pre-install

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (c) 2017-2025 Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
#
# pylint: disable=C0103,C0114,C0115,C0116,C0301,C0302
# pylint: disable=R0902,R0904,R0911,R0912,R0914,R0915,R1705,R1710,E1121

# Note: this script requires at least Python 3.6 to run.
# Don't add changes not compatible with it, it is meant to report
# incompatible python versions.

"""
Dependency checker for Sphinx documentation Kernel build.

This module provides tools to check for all required dependencies needed to
build documentation using Sphinx, including system packages, Python modules
and LaTeX packages for PDF generation.

It detect packages for a subset of Linux distributions used by Kernel
maintainers, showing hints and missing dependencies.

The main class SphinxDependencyChecker handles the dependency checking logic
and provides recommendations for installing missing packages. It supports both
system package installations and  Python virtual environments. By default,
system pacage install is recommended.
"""

import argparse
import os
import re
import subprocess
import sys
from glob import glob


def parse_version(version):
    """Convert a major.minor.patch version into a tuple"""
    return tuple(int(x) for x in version.split("."))


def ver_str(version):
    """Returns a version tuple as major.minor.patch"""

    return ".".join([str(x) for x in version])


RECOMMENDED_VERSION = parse_version("3.4.3")
MIN_PYTHON_VERSION = parse_version("3.7")


class DepManager:
    """
    Manage package dependencies. There are three types of dependencies:

    - System: dependencies required for docs build;
    - Python: python dependencies for a native distro Sphinx install;
    - PDF: dependencies needed by PDF builds.

    Each dependency can be mandatory or optional. Not installing an optional
    dependency won't break the build, but will cause degradation at the
    docs output.
    """

    # Internal types of dependencies. Don't use them outside DepManager class.
    _SYS_TYPE = 0
    _PHY_TYPE = 1
    _PDF_TYPE = 2

    # Dependencies visible outside the class.
    # The keys are tuple with: (type, is_mandatory flag).
    #
    # Currently we're not using all optional dep types. Yet, we'll keep all
    # possible combinations here. They're not many, and that makes easier
    # if later needed and for the name() method below

    SYSTEM_MANDATORY = (_SYS_TYPE, True)
    PYTHON_MANDATORY = (_PHY_TYPE, True)
    PDF_MANDATORY = (_PDF_TYPE, True)

    SYSTEM_OPTIONAL = (_SYS_TYPE, False)
    PYTHON_OPTIONAL = (_PHY_TYPE, False)
    PDF_OPTIONAL = (_PDF_TYPE, True)

    def __init__(self, pdf):
        """
        Initialize internal vars:

        - missing: missing dependencies list, containing a distro-independent
                   name for a missing dependency and its type.
        - missing_pkg: ancillary dict containing missing dependencies in
                       distro namespace, organized by type.
        - need: total number of needed dependencies. Never cleaned.
        - optional: total number of optional dependencies. Never cleaned.
        - pdf: Is PDF support enabled?
        """
        self.missing = {}
        self.missing_pkg = {}
        self.need = 0
        self.optional = 0
        self.pdf = pdf

    @staticmethod
    def name(dtype):
        """
        Ancillary routine to output a warn/error message reporting
        missing dependencies.
        """
        if dtype[0] == DepManager._SYS_TYPE:
            msg = "build"
        elif dtype[0] == DepManager._PHY_TYPE:
            msg = "Python"
        else:
            msg = "PDF"

        if dtype[1]:
            return f"ERROR: {msg} mandatory deps missing"
        else:
            return f"Warning: {msg} optional deps missing"

    @staticmethod
    def is_optional(dtype):
        """Ancillary routine to report if a dependency is optional"""
        return not dtype[1]

    @staticmethod
    def is_pdf(dtype):
        """Ancillary routine to report if a dependency is for PDF generation"""
        if dtype[0] == DepManager._PDF_TYPE:
            return True

        return False

    def add_package(self, package, dtype):
        """
        Add a package at the self.missing() dictionary.
        Doesn't update missing_pkg.
        """
        is_optional = DepManager.is_optional(dtype)
        self.missing[package] = dtype
        if is_optional:
            self.optional += 1
        else:
            self.need += 1

    def del_package(self, package):
        """
        Remove a package at the self.missing() dictionary.
        Doesn't update missing_pkg.
        """
        if packag