| # SPDX-License-Identifier: Apache-2.0 |
| # Copyright 2018 The Meson development team |
| |
| from __future__ import annotations |
| |
| '''This module provides helper functions for generating documentation using hotdoc''' |
| |
| import os, subprocess |
| import typing as T |
| |
| from . import ExtensionModule, ModuleReturnValue, ModuleInfo |
| from .. import build, mesonlib, mlog |
| from ..build import CustomTarget, CustomTargetIndex |
| from ..dependencies import Dependency, InternalDependency |
| from ..interpreterbase import ( |
| InvalidArguments, noPosargs, noKwargs, typed_kwargs, FeatureDeprecated, |
| ContainerTypeInfo, KwargInfo, typed_pos_args |
| ) |
| from ..interpreter.interpreterobjects import _CustomTargetHolder |
| from ..interpreter.type_checking import NoneType |
| from ..mesonlib import File, MesonException |
| from ..programs import ExternalProgram |
| |
| if T.TYPE_CHECKING: |
| from typing_extensions import TypedDict |
| |
| from . import ModuleState |
| from ..environment import Environment |
| from ..interpreter import Interpreter |
| from ..interpreterbase import TYPE_kwargs, TYPE_var |
| |
| _T = T.TypeVar('_T') |
| |
| class GenerateDocKwargs(TypedDict): |
| sitemap: T.Union[str, File, CustomTarget, CustomTargetIndex] |
| index: T.Union[str, File, CustomTarget, CustomTargetIndex] |
| project_version: str |
| html_extra_theme: T.Optional[str] |
| include_paths: T.List[str] |
| dependencies: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]] |
| depends: T.List[T.Union[CustomTarget, CustomTargetIndex]] |
| gi_c_source_roots: T.List[str] |
| extra_assets: T.List[str] |
| extra_extension_paths: T.List[str] |
| subprojects: T.List['HotdocTarget'] |
| install: bool |
| |
| def ensure_list(value: T.Union[_T, T.List[_T]]) -> T.List[_T]: |
| if not isinstance(value, list): |
| return [value] |
| return value |
| |
| |
| MIN_HOTDOC_VERSION = '0.8.100' |
| |
| file_types = (str, File, CustomTarget, CustomTargetIndex) |
| |
| |
| class HotdocExternalProgram(ExternalProgram): |
| def run_hotdoc(self, cmd: T.List[str]) -> int: |
| return subprocess.run(self.get_command() + cmd, stdout=subprocess.DEVNULL).returncode |
| |
| |
| class HotdocTargetBuilder: |
| |
| def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram, interpreter: Interpreter, kwargs): |
| self.hotdoc = hotdoc |
| self.build_by_default = kwargs.pop('build_by_default', False) |
| self.kwargs = kwargs |
| self.name = name |
| self.state = state |
| self.interpreter = interpreter |
| self.include_paths: mesonlib.OrderedSet[str] = mesonlib.OrderedSet() |
| |
| self.builddir = state.environment.get_build_dir() |
| self.sourcedir = state.environment.get_source_dir() |
| self.subdir = state.subdir |
| self.build_command = state.environment.get_build_command() |
| |
| self.cmd: T.List[TYPE_var] = ['conf', '--project-name', name, "--disable-incremental-build", |
| '--output', os.path.join(self.builddir, self.subdir, self.name + '-doc')] |
| |
| self._extra_extension_paths = set() |
| self.extra_assets = set() |
| self.extra_depends = [] |
| self._subprojects = [] |
| |
| def process_known_arg(self, option: str, argname: T.Optional[str] = None, value_processor: T.Optional[T.Callable] = None) -> None: |
| if not argname: |
| argname = option.strip("-").replace("-", "_") |
| |
| value = self.kwargs.pop(argname) |
| if value is not None and value_processor: |
| value = value_processor(value) |
| |
| self.set_arg_value(option, value) |
| |
| def set_arg_value(self, option: str, value: TYPE_var) -> None: |
| if value is None: |
| return |
| |
| if isinstance(value, bool): |
| if value: |
| self.cmd.append(option) |
| elif isinstance(value, list): |
| # Do not do anything on empty lists |
| if value: |
| # https://bugs.python.org/issue9334 (from 2010 :( ) |
| # The syntax with nargs=+ is inherently ambiguous |
| # A workaround for this case is to simply prefix with a space |
| # every value starting with a dash |
| escaped_value = [] |
| for e in value: |
| if isinstance(e, str) and e.startswith('-'): |
| escaped_value += [' %s' % e] |
| else: |
| escaped_value += [e] |
| if option: |
| self.cmd.extend([option] + escaped_value) |
| else: |
| self.cmd.extend(escaped_value) |
| else: |
| # argparse gets confused if value(s) start with a dash. |
| # When an option expects a single value, the unambiguous way |
| # to specify it is with = |
| if isinstance(value, str): |
| self.cmd.extend([f'{option}={value}']) |
| else: |
| self.cmd.extend([option, value]) |
| |
| def check_extra_arg_type(self, arg: str, value: TYPE_var) -> None: |
| if isinstance(value, list): |
| for v in value: |
| self.check_extra_arg_type(arg, v) |
| return |
| |
| valid_types = (str, bool, File, build.IncludeDirs, CustomTarget, CustomTargetIndex, build.BuildTarget) |
| if not isinstance(value, valid_types): |
| raise InvalidArguments('Argument "{}={}" should be of type: {}.'.format( |
| arg, value, [t.__name__ for t in valid_types])) |
| |
| def process_extra_args(self) -> None: |
| for arg, value in self.kwargs.items(): |
| option = "--" + arg.replace("_", "-") |
| self.check_extra_arg_type(arg, value) |
| self.set_arg_value(option, value) |
| |
| def get_value(self, types, argname, default=None, value_processor=None, |
| mandatory=False, force_list=False): |
| if not isinstance(types, list): |
| types = [types] |
| try: |
| uvalue = value = self.kwargs.pop(argname) |
| if value_processor: |
| value = value_processor(value) |
| |
| for t in types: |
| if isinstance(value, t): |
| if force_list and not isinstance(value, list): |
| return [value], uvalue |
| return value, uvalue |
| raise MesonException(f"{argname} field value {value} is not valid," |
| f" valid types are {types}") |
| except KeyError: |
| if mandatory: |
| raise MesonException(f"{argname} mandatory field not found") |
| |
| if default is not None: |
| return default, default |
| |
| return None, None |
| |
| def add_extension_paths(self, paths: T.Union[T.List[str], T.Set[str]]) -> None: |
| for path in paths: |
| if path in self._extra_extension_paths: |
| continue |
| |
| self._extra_extension_paths.add(path) |
| self.cmd.extend(["--extra-extension-path", path]) |
| |
| def replace_dirs_in_string(self, string: str) -> str: |
| return string.replace("@SOURCE_ROOT@", self.sourcedir).replace("@BUILD_ROOT@", self.builddir) |
| |
| def process_gi_c_source_roots(self) -> None: |
| if self.hotdoc.run_hotdoc(['--has-extension=gi-extension']) != 0: |
| return |
| |
| value = self.kwargs.pop('gi_c_source_roots') |
| value.extend([ |
| os.path.join(self.sourcedir, self.state.root_subdir), |
| os.path.join(self.builddir, self.state.root_subdir) |
| ]) |
| |
| self.cmd += ['--gi-c-source-roots'] + value |
| |
| def process_dependencies(self, deps: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]) -> T.List[str]: |
| cflags = set() |
| for dep in mesonlib.listify(ensure_list(deps)): |
| if isinstance(dep, InternalDependency): |
| inc_args = self.state.get_include_args(dep.include_directories) |
| cflags.update([self.replace_dirs_in_string(x) |
| for x in inc_args]) |
| cflags.update(self.process_dependencies(dep.libraries)) |
| cflags.update(self.process_dependencies(dep.sources)) |
| cflags.update(self.process_dependencies(dep.ext_deps)) |
| elif isinstance(dep, Dependency): |
| cflags.update(dep.get_compile_args()) |
| elif isinstance(dep, (build.StaticLibrary, build.SharedLibrary)): |
| self.extra_depends.append(dep) |
| for incd in dep.get_include_dirs(): |
| cflags.update(incd.get_incdirs()) |
| elif isinstance(dep, HotdocTarget): |
| # Recurse in hotdoc target dependencies |
| self.process_dependencies(dep.get_target_dependencies()) |
| self._subprojects.extend(dep.subprojects) |
| self.process_dependencies(dep.subprojects) |
| self.include_paths.add(os.path.join(self.builddir, dep.hotdoc_conf.subdir)) |
| self.cmd += ['--extra-assets=' + p for p in dep.extra_assets] |
| self.add_extension_paths(dep.extra_extension_paths) |
| elif isinstance(dep, (CustomTarget, build.BuildTarget)): |
| self.extra_depends.append(dep) |
| elif isinstance(dep, CustomTargetIndex): |
| self.extra_depends.append(dep.target) |
| |
| return [f.strip('-I') for f in cflags] |
| |
| def process_extra_assets(self) -> None: |
| self._extra_assets = self.kwargs.pop('extra_assets') |
| |
| for assets_path in self._extra_assets: |
| self.cmd.extend(["--extra-assets", assets_path]) |
| |
| def process_subprojects(self) -> None: |
| value = self.kwargs.pop('subprojects') |
| |
| self.process_dependencies(value) |
| self._subprojects.extend(value) |
| |
| def flatten_config_command(self) -> T.List[str]: |
| cmd = [] |
| for arg in mesonlib.listify(self.cmd, flatten=True): |
| if isinstance(arg, File): |
| arg = arg.absolute_path(self.state.environment.get_source_dir(), |
| self.state.environment.get_build_dir()) |
| elif isinstance(arg, build.IncludeDirs): |
| for inc_dir in arg.get_incdirs(): |
| cmd.append(os.path.join(self.sourcedir, arg.get_curdir(), inc_dir)) |
| cmd.append(os.path.join(self.builddir, arg.get_curdir(), inc_dir)) |
| |
| continue |
| elif isinstance(arg, (build.BuildTarget, CustomTarget)): |
| self.extra_depends.append(arg) |
| arg = self.interpreter.backend.get_target_filename_abs(arg) |
| elif isinstance(arg, CustomTargetIndex): |
| self.extra_depends.append(arg.target) |
| arg = self.interpreter.backend.get_target_filename_abs(arg) |
| |
| cmd.append(arg) |
| |
| return cmd |
| |
| def generate_hotdoc_config(self) -> None: |
| cwd = os.path.abspath(os.curdir) |
| ncwd = os.path.join(self.sourcedir, self.subdir) |
| mlog.log('Generating Hotdoc configuration for: ', mlog.bold(self.name)) |
| os.chdir(ncwd) |
| if self.hotdoc.run_hotdoc(self.flatten_config_command()) != 0: |
| raise MesonException('hotdoc failed to configure') |
| os.chdir(cwd) |
| |
| def ensure_file(self, value: T.Union[str, File, CustomTarget, CustomTargetIndex]) -> T.Union[File, CustomTarget, CustomTargetIndex]: |
| if isinstance(value, list): |
| res = [] |
| for val in value: |
| res.append(self.ensure_file(val)) |
| return res |
| |
| if isinstance(value, str): |
| return File.from_source_file(self.sourcedir, self.subdir, value) |
| |
| return value |
| |
| def ensure_dir(self, value: str) -> str: |
| if os.path.isabs(value): |
| _dir = value |
| else: |
| _dir = os.path.join(self.sourcedir, self.subdir, value) |
| |
| if not os.path.isdir(_dir): |
| raise InvalidArguments(f'"{_dir}" is not a directory.') |
| |
| return os.path.relpath(_dir, os.path.join(self.builddir, self.subdir)) |
| |
| def check_forbidden_args(self) -> None: |
| for arg in ['conf_file']: |
| if arg in self.kwargs: |
| raise InvalidArguments(f'Argument "{arg}" is forbidden.') |
| |
| def make_targets(self) -> T.Tuple[HotdocTarget, mesonlib.ExecutableSerialisation]: |
| self.check_forbidden_args() |
| self.process_known_arg("--index", value_processor=self.ensure_file) |
| self.process_known_arg("--project-version") |
| self.process_known_arg("--sitemap", value_processor=self.ensure_file) |
| self.process_known_arg("--html-extra-theme", value_processor=self.ensure_dir) |
| self.include_paths.update(self.ensure_dir(v) for v in self.kwargs.pop('include_paths')) |
| self.process_known_arg('--c-include-directories', argname="dependencies", value_processor=self.process_dependencies) |
| self.process_gi_c_source_roots() |
| self.process_extra_assets() |
| self.add_extension_paths(self.kwargs.pop('extra_extension_paths')) |
| self.process_subprojects() |
| self.extra_depends.extend(self.kwargs.pop('depends')) |
| |
| install = self.kwargs.pop('install') |
| self.process_extra_args() |
| |
| fullname = self.name + '-doc' |
| hotdoc_config_name = fullname + '.json' |
| hotdoc_config_path = os.path.join( |
| self.builddir, self.subdir, hotdoc_config_name) |
| with open(hotdoc_config_path, 'w', encoding='utf-8') as f: |
| f.write('{}') |
| |
| self.cmd += ['--conf-file', hotdoc_config_path] |
| self.include_paths.add(os.path.join(self.builddir, self.subdir)) |
| self.include_paths.add(os.path.join(self.sourcedir, self.subdir)) |
| |
| depfile = os.path.join(self.builddir, self.subdir, self.name + '.deps') |
| self.cmd += ['--deps-file-dest', depfile] |
| |
| for path in self.include_paths: |
| self.cmd.extend(['--include-path', path]) |
| |
| if self.state.environment.coredata.get_option(mesonlib.OptionKey('werror', subproject=self.state.subproject)): |
| self.cmd.append('--fatal-warnings') |
| self.generate_hotdoc_config() |
| |
| target_cmd = self.build_command + ["--internal", "hotdoc"] + \ |
| self.hotdoc.get_command() + ['run', '--conf-file', hotdoc_config_name] + \ |
| ['--builddir', os.path.join(self.builddir, self.subdir)] |
| |
| target = HotdocTarget(fullname, |
| subdir=self.subdir, |
| subproject=self.state.subproject, |
| environment=self.state.environment, |
| hotdoc_conf=File.from_built_file( |
| self.subdir, hotdoc_config_name), |
| extra_extension_paths=self._extra_extension_paths, |
| extra_assets=self._extra_assets, |
| subprojects=self._subprojects, |
| command=target_cmd, |
| extra_depends=self.extra_depends, |
| outputs=[fullname], |
| sources=[], |
| depfile=os.path.basename(depfile), |
| build_by_default=self.build_by_default) |
| |
| install_script = None |
| if install: |
| datadir = os.path.join(self.state.get_option('prefix'), self.state.get_option('datadir')) |
| devhelp = self.kwargs.get('devhelp_activate', False) |
| if not isinstance(devhelp, bool): |
| FeatureDeprecated.single_use('hotdoc.generate_doc() devhelp_activate must be boolean', '1.1.0', self.state.subproject) |
| devhelp = False |
| if devhelp: |
| install_from = os.path.join(fullname, 'devhelp') |
| install_to = os.path.join(datadir, 'devhelp') |
| else: |
| install_from = os.path.join(fullname, 'html') |
| install_to = os.path.join(datadir, 'doc', self.name, 'html') |
| |
| install_script = self.state.backend.get_executable_serialisation(self.build_command + [ |
| "--internal", "hotdoc", |
| "--install", install_from, |
| "--docdir", install_to, |
| '--name', self.name, |
| '--builddir', os.path.join(self.builddir, self.subdir)] + |
| self.hotdoc.get_command() + |
| ['run', '--conf-file', hotdoc_config_name]) |
| install_script.tag = 'doc' |
| |
| return (target, install_script) |
| |
| |
| class HotdocTargetHolder(_CustomTargetHolder['HotdocTarget']): |
| def __init__(self, target: HotdocTarget, interp: Interpreter): |
| super().__init__(target, interp) |
| self.methods.update({'config_path': self.config_path_method}) |
| |
| @noPosargs |
| @noKwargs |
| def config_path_method(self, *args: T.Any, **kwargs: T.Any) -> str: |
| conf = self.held_object.hotdoc_conf.absolute_path(self.interpreter.environment.source_dir, |
| self.interpreter.environment.build_dir) |
| return conf |
| |
| |
| class HotdocTarget(CustomTarget): |
| def __init__(self, name: str, subdir: str, subproject: str, hotdoc_conf: File, |
| extra_extension_paths: T.Set[str], extra_assets: T.List[str], |
| subprojects: T.List['HotdocTarget'], environment: Environment, **kwargs: T.Any): |
| super().__init__(name, subdir, subproject, environment, **kwargs, absolute_paths=True) |
| self.hotdoc_conf = hotdoc_conf |
| self.extra_extension_paths = extra_extension_paths |
| self.extra_assets = extra_assets |
| self.subprojects = subprojects |
| |
| def __getstate__(self) -> dict: |
| # Make sure we do not try to pickle subprojects |
| res = self.__dict__.copy() |
| res['subprojects'] = [] |
| |
| return res |
| |
| |
| class HotDocModule(ExtensionModule): |
| |
| INFO = ModuleInfo('hotdoc', '0.48.0') |
| |
| def __init__(self, interpreter: Interpreter): |
| super().__init__(interpreter) |
| self.hotdoc = HotdocExternalProgram('hotdoc') |
| if not self.hotdoc.found(): |
| raise MesonException('hotdoc executable not found') |
| version = self.hotdoc.get_version(interpreter) |
| if not mesonlib.version_compare(version, f'>={MIN_HOTDOC_VERSION}'): |
| raise MesonException(f'hotdoc {MIN_HOTDOC_VERSION} required but not found.)') |
| |
| self.methods.update({ |
| 'has_extensions': self.has_extensions, |
| 'generate_doc': self.generate_doc, |
| }) |
| |
| @noKwargs |
| @typed_pos_args('hotdoc.has_extensions', varargs=str, min_varargs=1) |
| def has_extensions(self, state: ModuleState, args: T.Tuple[T.List[str]], kwargs: TYPE_kwargs) -> bool: |
| return self.hotdoc.run_hotdoc([f'--has-extension={extension}' for extension in args[0]]) == 0 |
| |
| @typed_pos_args('hotdoc.generate_doc', str) |
| @typed_kwargs( |
| 'hotdoc.generate_doc', |
| KwargInfo('sitemap', file_types, required=True), |
| KwargInfo('index', file_types, required=True), |
| KwargInfo('project_version', str, required=True), |
| KwargInfo('html_extra_theme', (str, NoneType)), |
| KwargInfo('include_paths', ContainerTypeInfo(list, str), listify=True, default=[]), |
| # --c-include-directories |
| KwargInfo( |
| 'dependencies', |
| ContainerTypeInfo(list, (Dependency, build.StaticLibrary, build.SharedLibrary, |
| CustomTarget, CustomTargetIndex)), |
| listify=True, |
| default=[], |
| ), |
| KwargInfo( |
| 'depends', |
| ContainerTypeInfo(list, (CustomTarget, CustomTargetIndex)), |
| listify=True, |
| default=[], |
| since='0.64.1', |
| ), |
| KwargInfo('gi_c_source_roots', ContainerTypeInfo(list, str), listify=True, default=[]), |
| KwargInfo('extra_assets', ContainerTypeInfo(list, str), listify=True, default=[]), |
| KwargInfo('extra_extension_paths', ContainerTypeInfo(list, str), listify=True, default=[]), |
| KwargInfo('subprojects', ContainerTypeInfo(list, HotdocTarget), listify=True, default=[]), |
| KwargInfo('install', bool, default=False), |
| allow_unknown=True |
| ) |
| def generate_doc(self, state: ModuleState, args: T.Tuple[str], kwargs: GenerateDocKwargs) -> ModuleReturnValue: |
| project_name = args[0] |
| if any(isinstance(x, (CustomTarget, CustomTargetIndex)) for x in kwargs['dependencies']): |
| FeatureDeprecated.single_use('hotdoc.generate_doc dependencies argument with custom_target', |
| '0.64.1', state.subproject, 'use `depends`', state.current_node) |
| builder = HotdocTargetBuilder(project_name, state, self.hotdoc, self.interpreter, kwargs) |
| target, install_script = builder.make_targets() |
| targets: T.List[T.Union[HotdocTarget, mesonlib.ExecutableSerialisation]] = [target] |
| if install_script: |
| targets.append(install_script) |
| |
| return ModuleReturnValue(target, targets) |
| |
| |
| def initialize(interpreter: Interpreter) -> HotDocModule: |
| mod = HotDocModule(interpreter) |
| mod.interpreter.append_holder_map(HotdocTarget, HotdocTargetHolder) |
| return mod |
