Merge pull request #137 from openSUSE/toms/fix-doc

Fix documentation crash due to renaming

Author: tomschr

changelog.d/137.doc.rst

@@ -0,0 +1 @@
+Fix documentation issues due to renaming of classes with underscores.

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

@@ -0,0 +1,37 @@
+docbuild.cli.callback
+=====================
+
+.. py:module:: docbuild.cli.callback
+
+.. autoapi-nested-parse::
+
+   Click callback to validate doctype strings.
+
+
+
+Functions
+---------
+
+.. autoapisummary::
+
+   docbuild.cli.callback.validate_doctypes
+
+
+Module Contents
+---------------
+
+.. py:function:: validate_doctypes(ctx: click.Context, param: click.Parameter | None, doctypes: tuple[str, Ellipsis]) -> list[docbuild.models.doctype.Doctype]
+
+   Click callback function to validate a list of doctype strings.
+
+   Each string must conform to the format: PRODUCT/DOCSET@LIFECYCLE/LANGS
+   LANGS can be a single language code, a comma-separated list (no spaces),
+   or '*' for all.
+   Defaults and wildcards (*) are handled.
+
+   :param param: The click parameter that triggered this callback.
+   :param doctypes: A tuple of doctype strings to validate.
+   :return: A list of validated Doctype objects.
+   :raises click.Abort: If any doctype string is invalid, the command is aborted.
+
+

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

@@ -29,7 +29,7 @@ Functions
 Package Contents
 ----------------
 
-.. py:function:: metadata(ctx: click.Context, doctypes: tuple[docbuild.models.doctype.Doctype]) -> None
+.. py:function:: metadata(ctx: click.Context, doctypes: tuple[docbuild.models.doctype.Doctype], exitfirst: bool, skip_repo_update: bool) -> None
 
    Subcommand to create metadata files.
 

docs/source/reference/_autoapi/docbuild/cli/cmd_metadata/metaprocess/index.rst

@@ -15,29 +15,38 @@ Functions
 .. autoapisummary::
 
    docbuild.cli.cmd_metadata.metaprocess.get_deliverable_from_doctype
+   docbuild.cli.cmd_metadata.metaprocess.collect_files_flat
    docbuild.cli.cmd_metadata.metaprocess.process_deliverable
+   docbuild.cli.cmd_metadata.metaprocess.update_repositories
    docbuild.cli.cmd_metadata.metaprocess.process_doctype
+   docbuild.cli.cmd_metadata.metaprocess.store_productdocset_json
    docbuild.cli.cmd_metadata.metaprocess.process
 
 
 Module Contents
 ---------------
 
-.. py:function:: get_deliverable_from_doctype(root: lxml.etree._ElementTree, context: docbuild.cli.context.DocBuildContext, doctype: docbuild.models.doctype.Doctype) -> list[docbuild.models.deliverable.Deliverable]
+.. py:function:: get_deliverable_from_doctype(root: lxml.etree._ElementTree, doctype: docbuild.models.doctype.Doctype) -> list[docbuild.models.deliverable.Deliverable]
 
    Get deliverable from doctype.
 
    :param root: The stitched XML node containing configuration.
-   :param context: The DocBuildContext containing environment configuration.
    :param doctype: The Doctype object to process.
    :return: A list of deliverables for the given doctype.
 
 
+.. py:function:: collect_files_flat(doctypes: collections.abc.Sequence[docbuild.models.doctype.Doctype], basedir: pathlib.Path | str) -> collections.abc.Generator[tuple[docbuild.models.doctype.Doctype, str, list[pathlib.Path]], Any, None]
+
+   Group files by (Product, Docset).
+
+   Yields (Doctype, Docset, List[Path]) using a flattened iteration strategy.
+
+
 .. py:function:: process_deliverable(deliverable: docbuild.models.deliverable.Deliverable, *, repo_dir: pathlib.Path, temp_repo_dir: pathlib.Path, base_cache_dir: pathlib.Path, meta_cache_dir: pathlib.Path, dapstmpl: str) -> bool
    :async:
 
 
-   Process a single deliverable.
+   Process a single deliverable asynchronously.
 
    This function creates a temporary clone of the deliverable's repository,
    checks out the correct branch, and then executes the DAPS command to
@@ -58,7 +67,17 @@ Module Contents
    :raises ValueError: If required configuration paths are missing.
 
 
-.. py:function:: process_doctype(root: lxml.etree._ElementTree, context: docbuild.cli.context.DocBuildContext, doctype: docbuild.models.doctype.Doctype) -> bool
+.. py:function:: update_repositories(deliverables: list[docbuild.models.deliverable.Deliverable], bare_repo_dir: pathlib.Path) -> bool
+   :async:
+
+
+   Update all Git repositories associated with the deliverables.
+
+   :param deliverables: A list of Deliverable objects.
+   :param bare_repo_dir: The root directory for storing permanent bare clones.
+
+
+.. py:function:: process_doctype(root: lxml.etree._ElementTree, context: docbuild.cli.context.DocBuildContext, doctype: docbuild.models.doctype.Doctype, *, exitfirst: bool = False, skip_repo_update: bool = False) -> list[docbuild.models.deliverable.Deliverable]
    :async:
 
 
@@ -67,16 +86,29 @@ Module Contents
    :param root: The stitched XML node containing configuration.
    :param context: The DocBuildContext containing environment configuration.
    :param doctypes: A tuple of Doctype objects to process.
+   :param exitfirst: If True, stop processing on the first failure.
+   :return: True if all files passed validation, False otherwise
+
+
+.. py:function:: store_productdocset_json(context: docbuild.cli.context.DocBuildContext, doctypes: collections.abc.Sequence[docbuild.models.doctype.Doctype], stitchnode: lxml.etree._ElementTree) -> None
+
+   Collect all JSON file for product/docset and create a single file.
+
+   :param context: Beschreibung
+   :param doctypes: Beschreibung
+   :param stitchnode: Beschreibung
 
 
-.. py:function:: process(context: docbuild.cli.context.DocBuildContext, doctypes: tuple[docbuild.models.doctype.Doctype]) -> int
+.. py:function:: process(context: docbuild.cli.context.DocBuildContext, doctypes: collections.abc.Sequence[docbuild.models.doctype.Doctype] | None, *, exitfirst: bool = False, skip_repo_update: bool = False) -> int
    :async:
 
 
    Asynchronous function to process metadata retrieval.
 
    :param context: The DocBuildContext containing environment configuration.
-   :param xmlfiles: A tuple or iterator of XML file paths to validate.
+   :param doctype: A Doctype object to process.
+   :param exitfirst: If True, stop processing on the first failure.
+   :param skip_repo_update: If True, skip updating Git repositories before processing.
    :raises ValueError: If no envconfig is found or if paths are not
        configured correctly.
    :return: 0 if all files passed validation, 1 if any failures occurred.

docs/source/reference/_autoapi/docbuild/cli/cmd_validate/process/ValidationResult.rst

@@ -0,0 +1,11 @@
+docbuild.cli.cmd_validate.process.ValidationResult
+==================================================
+
+.. py:class:: docbuild.cli.cmd_validate.process.ValidationResult
+
+   Normalized result of RNG validation.
+
+   :ivar success: True when validation passed.
+   :ivar exit_code: Exit code to return when validation fails (0 for success).
+   :ivar message: Optional human-readable message describing the failure.
+

docs/source/reference/_autoapi/docbuild/cli/cmd_validate/process/index.rst

@@ -9,6 +9,19 @@ docbuild.cli.cmd_validate.process
 
 
 
+Classes
+-------
+
+.. toctree::
+   :hidden:
+
+   /reference/_autoapi/docbuild/cli/cmd_validate/process/ValidationResult
+
+.. autoapisummary::
+
+   docbuild.cli.cmd_validate.process.ValidationResult
+
+
 Functions
 ---------
 
@@ -18,6 +31,10 @@ Functions
    docbuild.cli.cmd_validate.process.validate_rng
    docbuild.cli.cmd_validate.process.validate_rng_lxml
    docbuild.cli.cmd_validate.process.run_python_checks
+   docbuild.cli.cmd_validate.process.build_shortname
+   docbuild.cli.cmd_validate.process.run_validation
+   docbuild.cli.cmd_validate.process.parse_tree
+   docbuild.cli.cmd_validate.process.run_checks_and_display
    docbuild.cli.cmd_validate.process.process_file
    docbuild.cli.cmd_validate.process.process
 
@@ -35,7 +52,7 @@ Module Contents
    :param max_len: Maximum length for formatting the output.
 
 
-.. py:function:: validate_rng(xmlfile: pathlib.Path, rng_schema_path: pathlib.Path = PRODUCT_CONFIG_SCHEMA, *, xinclude: bool = True, idcheck: bool = True) -> tuple[bool, str]
+.. py:function:: validate_rng(xmlfile: pathlib.Path, rng_schema_path: pathlib.Path = PRODUCT_CONFIG_SCHEMA, *, xinclude: bool = True, idcheck: bool = True) -> subprocess.CompletedProcess
    :async:
 
 
@@ -46,7 +63,8 @@ Module Contents
    more robust for complex XInclude statements, including those with XPointer.
 
    :param xmlfile: The path to the XML file to validate.
-   :param rng_schema_path: The path to the RELAX NG schema file. It supports both RNC and RNG formats.
+   :param rng_schema_path: The path to the RELAX NG schema file.
+       It supports both RNC and RNG formats.
    :param xinclude: If True, resolve XIncludes with `xmllint` before validation.
    :param idcheck: If True, perform ID uniqueness checks.
    :return: A tuple containing a boolean success status and any output message.
@@ -74,6 +92,51 @@ Module Contents
    :return: A list of tuples containing check names and their results.
 
 
+.. py:function:: build_shortname(filepath: pathlib.Path | str) -> str
+
+   Return a shortened display name for ``filepath``.
+
+   :param filepath: Path-like object to shorten.
+   :returns: Shortened display name (last two path components or full path).
+
+
+.. py:function:: run_validation(filepath: pathlib.Path | str, method: str) -> ValidationResult
+   :async:
+
+
+   Run RNG validation using the selected method and normalize result.
+
+   :param filepath: Path to the XML file to validate.
+   :param method: Validation method name ("jing" or "lxml").
+   :returns: A :class:`ValidationResult` describing the outcome.
+
+
+.. py:function:: parse_tree(filepath: pathlib.Path | str) -> lxml.etree._ElementTree
+   :async:
+
+
+   Parse XML file using lxml in a background thread.
+
+   Exceptions from :func:`lxml.etree.parse` (for example
+   :class:`lxml.etree.XMLSyntaxError`) are propagated to the caller.
+
+   :param filepath: Path to the XML file to parse.
+   :returns: Parsed :class:`lxml.etree._ElementTree`.
+
+
+.. py:function:: run_checks_and_display(tree: lxml.etree._ElementTree, shortname: str, context: docbuild.cli.context.DocBuildContext, max_len: int) -> bool
+   :async:
+
+
+   Execute registered Python checks and print formatted results.
+
+   :param tree: Parsed XML tree to check.
+   :param shortname: Short name used for display output.
+   :param context: :class:`DocBuildContext` used to read verbosity.
+   :param max_len: Maximum length used for aligned output.
+   :returns: True when all checks succeeded (or when no checks are registered).
+
+
 .. py:function:: process_file(filepath: pathlib.Path | str, context: docbuild.cli.context.DocBuildContext, max_len: int) -> int
    :async:
 

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

@@ -26,6 +26,7 @@ Submodules
 .. toctree::
    :maxdepth: 1
 
+   /reference/_autoapi/docbuild/cli/callback/index
    /reference/_autoapi/docbuild/cli/cmd_build/index
    /reference/_autoapi/docbuild/cli/cmd_c14n/index
    /reference/_autoapi/docbuild/cli/cmd_cli/index

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

@@ -14,6 +14,16 @@ docbuild.config.app.PlaceholderResolver
 
 
 
+   .. py:method:: get_container_name() -> str
+
+      Public accessor for the current container/key name.
+
+      This provides a stable, public way to retrieve the human-readable
+      container name for diagnostics and tests without reaching into
+      private attributes.
+
+
+
    .. py:method:: replace() -> dict[str, Any]
 
       Replace all placeholders in the configuration.

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

@@ -15,6 +15,7 @@ Attributes
 .. autoapisummary::
 
    docbuild.config.app.MAX_RECURSION_DEPTH
+   docbuild.config.app.ConfigValue
 
 
 Exceptions
@@ -64,6 +65,13 @@ Module Contents
    The maximum recursion depth for placeholder replacement.
 
 
+.. py:type:: ConfigValue
+   :canonical: str | int | float | bool | list['ConfigValue'] | dict[str, 'ConfigValue']
+
+
+   A recursive type for values found in the configuration.
+
+
 .. py:function:: replace_placeholders(config: dict[str, Any] | None, max_recursion_depth: int = MAX_RECURSION_DEPTH) -> dict[str, Any] | None
 
    Replace placeholder values in a nested dictionary structure.

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

@@ -15,6 +15,7 @@ Functions
 .. autoapisummary::
 
    docbuild.config.xml.stitch.load_check_functions
+   docbuild.config.xml.stitch.log_memory_usage
    docbuild.config.xml.stitch.check_stitchfile
    docbuild.config.xml.stitch.create_stitchfile
 
@@ -27,6 +28,13 @@ Module Contents
    Load all check functions from :mod:`docbuild.config.xml.checks`.
 
 
+.. py:function:: log_memory_usage() -> int
+
+   Determine the memory usage.
+
+   :return: memory usage in kilobytes
+
+
 .. py:function:: check_stitchfile(tree: lxml.etree._Element | lxml.etree._ElementTree) -> bool
 
    Check the stitchfile for unresolved references.