# 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 from ..options import OptionKey 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.optstore.get_value_for(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