Skip to content

Commit 78224c3

Browse files
tomschrtomschr
committed
Update API doc
1 parent d265349 commit 78224c3

14 files changed

Lines changed: 316 additions & 36 deletions

File tree

‎docs/source/reference/_autoapi/docbuild/cli/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,5 +31,6 @@ Submodules
3131
/reference/_autoapi/docbuild/cli/config/index
3232
/reference/_autoapi/docbuild/cli/context/index
3333
/reference/_autoapi/docbuild/cli/defaults/index
34+
/reference/_autoapi/docbuild/cli/process_validation/index
3435

3536

‎docs/source/reference/_autoapi/docbuild/cli/process_validation/index.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
docbuild.cli.process_validation
2+
===============================
3+
4+
.. py:module:: docbuild.cli.process_validation
5+
6+
.. autoapi-nested-parse::
7+
8+
Module for processing XML validation in DocBuild.
9+
10+
11+
12+
Functions
13+
---------
14+
15+
.. autoapisummary::
16+
17+
docbuild.cli.process_validation.display_results
18+
docbuild.cli.process_validation.run_command
19+
docbuild.cli.process_validation.validate_rng
20+
docbuild.cli.process_validation.run_python_checks
21+
docbuild.cli.process_validation.process_file
22+
docbuild.cli.process_validation.process
23+
24+
25+
Module Contents
26+
---------------
27+
28+
.. py:function:: display_results(shortname: str, check_results: list[tuple[str, docbuild.config.xml.checks.CheckResult]], verbose: int, max_len: int) -> None
29+
30+
Display validation results based on verbosity level using rich.
31+
32+
:param shortname: Shortened name of the XML file being processed.
33+
:param check_results: List of tuples containing check names and their results.
34+
:param verbose: Verbosity level (0, 1, 2)
35+
:param max_len: Maximum length for formatting the output.
36+
37+
38+
.. py:function:: run_command(*args: str, env: dict[str, str] | None = None) -> tuple[int, str, str]
39+
:async:
40+
41+
42+
Run an external command and capture its output.
43+
44+
:param args: The command and its arguments separated as tuple elements.
45+
:param env: A dictionary of environment variables for the new process.
46+
:return: A tuple of (returncode, stdout, stderr).
47+
:raises FileNotFoundError: if the command is not found.
48+
49+
50+
.. py:function:: validate_rng(xmlfile: pathlib.Path, rng_schema_path: pathlib.Path = PRODUCT_CONFIG_SCHEMA, *, xinclude: bool = True) -> tuple[bool, str]
51+
:async:
52+
53+
54+
Validate an XML file against a RELAX NG schema using jing.
55+
56+
If `xinclude` is True (the default), this function resolves XIncludes by
57+
running `xmllint --xinclude` and piping its output to `jing`. This is
58+
more robust for complex XInclude statements, including those with XPointer.
59+
60+
:param xmlfile: The path to the XML file to validate.
61+
:param rng_schema_path: The path to the RELAX NG schema file. It supports
62+
both RNC and RNG formats.
63+
:param xinclude: If True, resolve XIncludes with `xmllint` before validation.
64+
:return: A tuple containing a boolean success status and any output message.
65+
66+
67+
.. py:function:: run_python_checks(tree: lxml.etree._ElementTree) -> list[tuple[str, docbuild.config.xml.checks.CheckResult]]
68+
:async:
69+
70+
71+
Run all registered Python-based checks against a parsed XML tree.
72+
73+
:param tree: The parsed XML element tree.
74+
:return: A list of tuples containing check names and their results.
75+
76+
77+
.. py:function:: process_file(filepath: pathlib.Path | str, context: docbuild.cli.context.DocBuildContext, max_len: int) -> int
78+
:async:
79+
80+
81+
Process a single file: RNG validation then Python checks.
82+
83+
:param filepath: The path to the XML file to process.
84+
:param context: The DocBuildContext.
85+
:param max_len: Maximum length for formatting the output.
86+
:param rng_schema_path: Optional path to an RNG schema for validation.
87+
:return: An exit code (0 for success, non-zero for failure).
88+
89+
90+
.. py:function:: process(context: docbuild.cli.context.DocBuildContext, xmlfiles: tuple[pathlib.Path | str, Ellipsis] | collections.abc.Iterator[pathlib.Path]) -> int
91+
:async:
92+
93+
94+
Asynchronous function to process validation.
95+
96+
:param context: The DocBuildContext containing environment configuration.
97+
:param xmlfiles: A tuple or iterator of XML file paths to validate.
98+
:raises ValueError: If no envconfig is found or if paths are not
99+
configured correctly.
100+
:return: 0 if all files passed validation, 1 if any failures occurred.
101+
102+

‎docs/source/reference/_autoapi/docbuild/config/app/CircularReferenceError.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
docbuild.config.app.CircularReferenceError
2+
==========================================
3+
4+
.. py:exception:: docbuild.config.app.CircularReferenceError
5+
6+
Bases: :py:obj:`ValueError`
7+
8+
.. autoapi-inheritance-diagram:: docbuild.config.app.CircularReferenceError
9+
:parts: 1
10+
11+
12+
Circular reference is detected in placeholder resolution.
13+

‎docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolutionError.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
docbuild.config.app.PlaceholderResolutionError
2+
==============================================
3+
4+
.. py:exception:: docbuild.config.app.PlaceholderResolutionError
5+
6+
Bases: :py:obj:`KeyError`
7+
8+
.. autoapi-inheritance-diagram:: docbuild.config.app.PlaceholderResolutionError
9+
:parts: 1
10+
11+
12+
Exception raised when a placeholder cannot be resolved.
13+

‎docs/source/reference/_autoapi/docbuild/config/app/PlaceholderResolver.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
docbuild.config.app.PlaceholderResolver
2+
=======================================
3+
4+
.. py:class:: docbuild.config.app.PlaceholderResolver(config: dict[str, Any], max_recursion_depth: int = MAX_RECURSION_DEPTH)
5+
6+
Handles placeholder resolution in configuration data.
7+
8+
9+
.. py:attribute:: PLACEHOLDER_PATTERN
10+
:type: re.Pattern[str]
11+
12+
Compiled regex for standard placeholders in configuration
13+
files (like ``{placeholder}``).
14+
15+
16+
17+
.. py:method:: replace() -> dict[str, Any]
18+
19+
Replace all placeholders in the configuration.
20+
21+
:return: The configuration with all placeholders resolved.
22+
:raises PlaceholderResolutionError: If a placeholder cannot be resolved.
23+
:raises CircularReferenceError: If a circular reference is detected.
24+
25+

‎docs/source/reference/_autoapi/docbuild/config/app/index.rst‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,37 @@ Attributes
1515
.. autoapisummary::
1616

1717
docbuild.config.app.Container
18-
docbuild.config.app.StackItem
1918
docbuild.config.app.MAX_RECURSION_DEPTH
2019

2120

21+
Exceptions
22+
----------
23+
24+
.. toctree::
25+
:hidden:
26+
27+
/reference/_autoapi/docbuild/config/app/PlaceholderResolutionError
28+
/reference/_autoapi/docbuild/config/app/CircularReferenceError
29+
30+
.. autoapisummary::
31+
32+
docbuild.config.app.PlaceholderResolutionError
33+
docbuild.config.app.CircularReferenceError
34+
35+
36+
Classes
37+
-------
38+
39+
.. toctree::
40+
:hidden:
41+
42+
/reference/_autoapi/docbuild/config/app/PlaceholderResolver
43+
44+
.. autoapisummary::
45+
46+
docbuild.config.app.PlaceholderResolver
47+
48+
2249
Functions
2350
---------
2451

@@ -35,11 +62,6 @@ Module Contents
3562
A dictionary or list container for any configuration data.
3663

3764

38-
.. py:data:: StackItem
39-
40-
A tuple representing a stack item for placeholder resolution.
41-
42-
4365
.. py:data:: MAX_RECURSION_DEPTH
4466
:type: int
4567
:value: 10
@@ -48,16 +70,18 @@ Module Contents
4870
The maximum recursion depth for placeholder replacement.
4971

5072

51-
.. py:function:: replace_placeholders(config: Container, max_recursion_depth: int = MAX_RECURSION_DEPTH) -> Container
73+
.. py:function:: replace_placeholders(config: dict[str, Any], max_recursion_depth: int = MAX_RECURSION_DEPTH) -> Container
5274
5375
Replace placeholder values in a nested dictionary structure.
5476

5577
* ``{foo}`` resolves from the current section.
5678
* ``{a.b.c}`` resolves deeply from the config.
5779
* ``{{foo}}`` escapes to literal ``{foo}``.
5880

59-
:param config: The loaded configuration dictionary.
81+
:param config: The configuration dictionary.
82+
:param max_recursion_depth: Maximum recursion depth for placeholder resolution.
6083
:return: A new dictionary with placeholders replaced.
61-
:raises KeyError: If a placeholder cannot be resolved.
84+
:raises PlaceholderResolutionError: If a placeholder cannot be resolved.
85+
:raises CircularReferenceError: If a circular reference is detected.
6286

6387

‎docs/source/reference/_autoapi/docbuild/config/xml/checks/index.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -127,9 +127,10 @@ Module Contents
127127

128128
.. py:function:: check_duplicated_url_in_extralinks(tree: lxml.etree._Element | lxml.etree._ElementTree) -> CheckResult
129129
130-
Check that url attributes in extralinks are unique.
130+
Check that url attributes in extralinks are unique within each language.
131131

132-
Make sure each URL appears only once within a given external links section.
132+
Make sure each URL appears only once within a given language in external
133+
links section.
133134

134135
.. code-block:: xml
135136
@@ -147,7 +148,7 @@ Module Contents
147148
</external>
148149
149150
:param tree: The XML tree to check.
150-
:return: True if all url attributes in extralinks are unique, False otherwise.
151+
:return: CheckResult with success status and any error messages.
151152

152153

153154
.. py:function:: check_enabled_format(tree: lxml.etree._Element | lxml.etree._ElementTree) -> CheckResult

‎docs/source/reference/_autoapi/docbuild/config/xml/stitch/index.rst‎

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ Functions
1515
.. autoapisummary::
1616

1717
docbuild.config.xml.stitch.load_check_functions
18-
docbuild.config.xml.stitch.validate_xmlconfig
1918
docbuild.config.xml.stitch.create_stitchfile
2019

2120

@@ -27,21 +26,15 @@ Module Contents
2726
Load all check functions from :mod:`docbuild.config.xml.checks`.
2827

2928

30-
.. py:function:: validate_xmlconfig(xmlfile: str | pathlib.Path, parser: lxml.etree.XMLParser | None = None) -> bool
29+
.. py:function:: create_stitchfile(xmlfiles: collections.abc.Sequence[str | pathlib.Path], *, xmlparser: lxml.etree.XMLParser | None = None) -> lxml.etree._ElementTree
30+
:async:
3131

32-
Validate an XML config file.
3332

34-
:param xmlfile: The XML file to validate.
35-
:param xmlparser: An optional XML parser to use for validation.
36-
:return: the parsed :class:`lxml.etree.ElementTree` object.
33+
Asynchronously create a stitch file from a list of XML files.
3734

38-
39-
.. py:function:: create_stitchfile(configdir: str | pathlib.Path, *, filepattern: str = '[a-zA-Z0-9]*.xml', xmlparser: lxml.etree.XMLParser | None = None) -> lxml.etree._ElementTree
40-
41-
Create a stitch file from a config directory.
42-
43-
:param configdir: The config directory to search for XML files.
44-
:param filepattern: A glob pattern that matches files in configdir.
45-
:return: the stitched :class:`lxml.etree.ElementTree` object.
35+
:param xmlfiles: A sequence of XML file paths to stitch together.
36+
:param xmlparser: An optional XML parser to use.
37+
:return: all XML file stitched together into a
38+
:class:`lxml.etree.ElementTree` object.
4639

4740

‎docs/source/reference/_autoapi/docbuild/constants/index.rst‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,8 @@ Attributes
3636
docbuild.constants.APP_CONFIG_FILENAME
3737
docbuild.constants.ENV_CONFIG_FILENAME
3838
docbuild.constants.DEFAULT_ENV_CONFIG_FILENAME
39-
docbuild.constants.PLACEHOLDER_PATTERN
4039
docbuild.constants.BASE_LOG_DIR
40+
docbuild.constants.XMLDATADIR
4141

4242

4343
Module Contents
@@ -178,17 +178,15 @@ Module Contents
178178
used in production.
179179

180180

181-
.. py:data:: PLACEHOLDER_PATTERN
182-
:type: re.Pattern[str]
183-
184-
Compiled regex for standard placeholders in configuration files
185-
(like ``{placeholder}``).
186-
187-
188181
.. py:data:: BASE_LOG_DIR
189182
190183
The directory where log files will be stored, typically at
191184
:file:`~/.local/state/docbuild/logs` as recommended by the XDG Base
192185
Directory Specification.
193186

194187

188+
.. py:data:: XMLDATADIR
189+
190+
Directory where additional files (RNC, XSLT) for XML processing are stored.
191+
192+

‎docs/source/reference/_autoapi/docbuild/utils/contextmgr/TimerData.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
docbuild.utils.contextmgr.TimerData
2+
===================================
3+
4+
.. py:class:: docbuild.utils.contextmgr.TimerData
5+
6+
Data structure to hold timer information.
7+

0 commit comments

Comments
 (0)