usse/scrape/venv/lib/python3.10/site-packages/esbonio/sphinx_agent/config.py
2023-12-22 15:26:01 +01:00

161 lines
5.4 KiB
Python

import dataclasses
import inspect
import pathlib
from typing import Any
from typing import Dict
from typing import List
from typing import Literal
from typing import Optional
from typing import Union
from unittest import mock
from sphinx.application import Sphinx
from sphinx.cmd.build import main as sphinx_build
@dataclasses.dataclass
class SphinxConfig:
"""Configuration values to pass to the Sphinx application instance."""
src_dir: str
"""The directory containing the project's source."""
conf_dir: str
"""The directory containing the project's ``conf.py``."""
build_dir: str
"""The directory to write build outputs into."""
builder_name: str
"""The currently used builder name."""
doctree_dir: str
"""The directory to write doctrees into."""
config_overrides: Dict[str, Any] = dataclasses.field(default_factory=dict)
"""Any overrides to configuration values."""
force_full_build: bool = dataclasses.field(default=False)
"""Force a full build on startup."""
keep_going: bool = dataclasses.field(default=False)
"""Continue building when errors (from warnings) are encountered."""
num_jobs: Union[Literal["auto"], int] = dataclasses.field(default=1)
"""The number of jobs to use for parallel builds."""
quiet: bool = dataclasses.field(default=False)
"""Hide standard Sphinx output messages"""
silent: bool = dataclasses.field(default=False)
"""Hide all Sphinx output."""
tags: List[str] = dataclasses.field(default_factory=list)
"""Tags to enable during a build."""
verbosity: int = dataclasses.field(default=0)
"""The verbosity of Sphinx's output."""
version: Optional[str] = dataclasses.field(default=None)
"""Sphinx's version number."""
warning_is_error: bool = dataclasses.field(default=False)
"""Treat any warning as an error"""
@property
def parallel(self) -> int:
"""The parsed value of the ``num_jobs`` field."""
if self.num_jobs == "auto":
import multiprocessing
return multiprocessing.cpu_count()
return self.num_jobs
@classmethod
def fromcli(cls, args: List[str]):
"""Return the ``SphinxConfig`` instance that's equivalent to the given arguments.
Parameters
----------
args
The cli arguments you would normally pass to ``sphinx-build``
Returns
-------
Optional[SphinxConfig]
``None`` if the arguments could not be parsed, otherwise the set configuration
options derived from the sphinx build command.
"""
if args[0] == "sphinx-build":
args = args[1:]
# The easiest way to handle this is to just call sphinx-build but with
# the Sphinx app object patched out - then we just use all the args it
# was given!
with mock.patch("sphinx.cmd.build.Sphinx") as m_Sphinx:
sphinx_build(args)
if m_Sphinx.call_args is None:
return None
signature = inspect.signature(Sphinx)
keys = signature.parameters.keys()
values = m_Sphinx.call_args[0]
sphinx_args = {k: v for k, v in zip(keys, values)}
if sphinx_args is None:
return None
return cls(
src_dir=sphinx_args["srcdir"],
conf_dir=sphinx_args["confdir"],
build_dir=sphinx_args["outdir"],
builder_name=sphinx_args["buildername"],
doctree_dir=sphinx_args["doctreedir"],
config_overrides=sphinx_args.get("confoverrides", {}),
force_full_build=sphinx_args.get("freshenv", False),
keep_going=sphinx_args.get("keep_going", False),
num_jobs=sphinx_args.get("parallel", 1),
quiet=sphinx_args.get("status", 1) is None,
silent=sphinx_args.get("warning", 1) is None,
tags=sphinx_args.get("tags", []),
verbosity=sphinx_args.get("verbosity", 0),
warning_is_error=sphinx_args.get("warningiserror", False),
)
def to_application_args(self) -> Dict[str, Any]:
"""Convert this into the equivalent Sphinx application arguments."""
# On OSes like Fedora Silverblue, `/home` is symlinked to `/var/home`. This
# causes issues, since, depending on the origin of any path given to us `/home`
# may or may not be the true location of the file - which introduces consistency
# problems throughout the codebase.
#
# Resolving these paths here, should ensure that the agent always
# reports the true location of any given directory.
conf_dir = pathlib.Path(self.conf_dir).resolve()
build_dir = pathlib.Path(self.build_dir).resolve()
doctree_dir = pathlib.Path(self.doctree_dir).resolve()
src_dir = pathlib.Path(self.src_dir).resolve()
return {
"buildername": self.builder_name,
"confdir": str(conf_dir),
"confoverrides": self.config_overrides,
"doctreedir": str(doctree_dir),
"freshenv": self.force_full_build,
"keep_going": self.keep_going,
"outdir": str(build_dir),
"parallel": self.parallel,
"srcdir": str(src_dir),
"status": None,
"tags": self.tags,
"verbosity": self.verbosity,
"warning": None,
"warningiserror": self.warning_is_error,
}