The Meson Build System
http://mesonbuild.com/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
485 lines
21 KiB
485 lines
21 KiB
# 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
|
|
|