WIP: Add serialization of missing Description

tomschr · tomschr · commit 844dc3ed9fff · 2026-02-09T14:20:34.000+01:00
The `&lt;desc&gt;` element in the XML configuration contains language-specific
descriptions. It is used in the index pages of each product release.

This PR adds the missing handling of this element.

* Build `Description` model for `Manifest`
* In `Deliverable`, create new methods (see below). They transform the
  `&lt;desc&gt;` element
  * `all_categories`: Return the categories of the deliverable.
  * `categories`: Return the categories from the product node.
  * `categories_from_root`: Return the categories from the root node.
* For submodels of `Manifest`, add serialization method (e.g., for `lang` attribute)
* Improve test cases
* Update doc sources of auto API
diff --git a/changelog.d/155.feature.rst b/changelog.d/155.feature.rst
@@ -0,0 +1 @@
+Add serialization of missing :class:`~docserv.models.deliverable.Description`.
diff --git a/docs/source/reference/_autoapi/docbuild/models/config_model/index.rst b/docs/source/reference/_autoapi/docbuild/models/config_model/index.rst
diff --git a/docs/source/reference/_autoapi/docbuild/models/deliverable/Deliverable.rst b/docs/source/reference/_autoapi/docbuild/models/deliverable/Deliverable.rst
@@ -11,6 +11,50 @@ docbuild.models.deliverable.Deliverable
    deliverable.
 
 
+   .. py:property:: all_categories
+      :type: collections.abc.Generator[lxml.etree._Element, None, None]
+
+
+      Return the groups (formerly categories) of the deliverable.
+
+      Yield all elements from the product and root node.
+
+      :yield: The elements categories/category and category.
+
+
+
+   .. py:property:: categories
+      :type: collections.abc.Generator[lxml.etree._Element, None, None]
+
+
+      Return the groups (formerly categories) from the product node.
+
+      Yield all elements under the product were this deliverable belongs to.
+
+      :yield: The elements categories/category and category.
+
+
+
+   .. py:property:: categories_from_root
+      :type: collections.abc.Generator[lxml.etree._Element, None, None]
+
+
+      Return the groups (formerly categories) from the root node.
+
+      Yield all elements under the root node.
+
+      :yield: The elements categories/category and category.
+
+
+
+   .. py:property:: desc
+      :type: collections.abc.Generator[lxml.etree._Element, None, None]
+
+
+      Return the <desc> from the product node.
+
+
+
    .. py:property:: productid
       :type: str | None
 
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Archive.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Archive.rst
@@ -0,0 +1,19 @@
+docbuild.models.manifest.Archive
+================================
+
+.. py:class:: docbuild.models.manifest.Archive(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Archive
+      :parts: 1
+
+
+   Represents an archive (e.g., a ZIP file) for a product/docset.
+
+
+   .. py:method:: serialize_lang(value: docbuild.models.language.LanguageCode, info: pydantic.SerializationInfo) -> str
+
+      Serialize LanguageCode to a string like 'en-us'.
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Category.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Category.rst
@@ -0,0 +1,13 @@
+docbuild.models.manifest.Category
+=================================
+
+.. py:class:: docbuild.models.manifest.Category(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Category
+      :parts: 1
+
+
+   Represents a category for a product/docset.
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/CategoryTranslation.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/CategoryTranslation.rst
@@ -0,0 +1,19 @@
+docbuild.models.manifest.CategoryTranslation
+============================================
+
+.. py:class:: docbuild.models.manifest.CategoryTranslation(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.CategoryTranslation
+      :parts: 1
+
+
+   Represents a translation for a category title.
+
+
+   .. py:method:: serialize_lang(value: docbuild.models.language.LanguageCode, info: pydantic.SerializationInfo) -> str
+
+      Serialize LanguageCode to a string like 'en-us'.
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Description.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Description.rst
@@ -0,0 +1,30 @@
+docbuild.models.manifest.Description
+====================================
+
+.. py:class:: docbuild.models.manifest.Description(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Description
+      :parts: 1
+
+
+   Represents a description for a product/docset.
+
+
+   .. py:method:: serialize_lang(value: docbuild.models.language.LanguageCode, info: pydantic.SerializationInfo) -> str
+
+      Serialize LanguageCode to a string like 'en-us'.
+
+
+
+   .. py:method:: from_xml_node(node: lxml.etree._Element) -> collections.abc.Generator[Self, None, None]
+      :classmethod:
+
+
+      Extract descriptions from a parent XML node.
+
+      :param node: a node pointing to ``<product>``
+      :yield:
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Document.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Document.rst
@@ -0,0 +1,27 @@
+docbuild.models.manifest.Document
+=================================
+
+.. py:class:: docbuild.models.manifest.Document(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Document
+      :parts: 1
+
+
+   Represents a single document within the manifest.
+
+
+   .. py:method:: coerce_rank(value: str | int | None) -> int | None
+      :classmethod:
+
+
+      Coerce rank from string to int, handling empty strings.
+
+
+
+   .. py:method:: serialize_rank(value: int | str | None, info: pydantic.SerializationInfo) -> str
+
+      Serialize rank to an empty string if None.
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/DocumentFormat.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/DocumentFormat.rst
@@ -0,0 +1,13 @@
+docbuild.models.manifest.DocumentFormat
+=======================================
+
+.. py:class:: docbuild.models.manifest.DocumentFormat(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.DocumentFormat
+      :parts: 1
+
+
+   Represents the available formats for a document.
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Manifest.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Manifest.rst
@@ -0,0 +1,13 @@
+docbuild.models.manifest.Manifest
+=================================
+
+.. py:class:: docbuild.models.manifest.Manifest(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Manifest
+      :parts: 1
+
+
+   Represents the aggregated metadata manifest for a product/docset.
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/Product.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/Product.rst
@@ -0,0 +1,13 @@
+docbuild.models.manifest.Product
+================================
+
+.. py:class:: docbuild.models.manifest.Product(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.Product
+      :parts: 1
+
+
+   Represents a single SUSE product.
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/SingleDocument.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/SingleDocument.rst
@@ -0,0 +1,19 @@
+docbuild.models.manifest.SingleDocument
+=======================================
+
+.. py:class:: docbuild.models.manifest.SingleDocument(/, **data: Any)
+
+   Bases: :py:obj:`pydantic.BaseModel`
+
+   .. autoapi-inheritance-diagram:: docbuild.models.manifest.SingleDocument
+      :parts: 1
+
+
+   Represent a single document.
+
+
+   .. py:method:: serialize_date(value: datetime.date | None, info: pydantic.SerializationInfo) -> str
+
+      Serialize date to 'YYYY-MM-DD' or an empty string if None.
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/manifest/index.rst b/docs/source/reference/_autoapi/docbuild/models/manifest/index.rst
@@ -0,0 +1,40 @@
+docbuild.models.manifest
+========================
+
+.. py:module:: docbuild.models.manifest
+
+.. autoapi-nested-parse::
+
+   Pydantic models for the metadata manifest structure.
+
+
+
+Classes
+-------
+
+.. toctree::
+   :hidden:
+
+   /reference/_autoapi/docbuild/models/manifest/Description
+   /reference/_autoapi/docbuild/models/manifest/CategoryTranslation
+   /reference/_autoapi/docbuild/models/manifest/Category
+   /reference/_autoapi/docbuild/models/manifest/Archive
+   /reference/_autoapi/docbuild/models/manifest/DocumentFormat
+   /reference/_autoapi/docbuild/models/manifest/SingleDocument
+   /reference/_autoapi/docbuild/models/manifest/Product
+   /reference/_autoapi/docbuild/models/manifest/Document
+   /reference/_autoapi/docbuild/models/manifest/Manifest
+
+.. autoapisummary::
+
+   docbuild.models.manifest.Description
+   docbuild.models.manifest.CategoryTranslation
+   docbuild.models.manifest.Category
+   docbuild.models.manifest.Archive
+   docbuild.models.manifest.DocumentFormat
+   docbuild.models.manifest.SingleDocument
+   docbuild.models.manifest.Product
+   docbuild.models.manifest.Document
+   docbuild.models.manifest.Manifest
+
+
diff --git a/src/docbuild/cli/cmd_metadata/metaprocess.py b/src/docbuild/cli/cmd_metadata/metaprocess.py
@@ -16,7 +16,7 @@
 from ...constants import DEFAULT_DELIVERABLES
 from ...models.deliverable import Deliverable
 from ...models.doctype import Doctype
-from ...models.manifest import Document, Manifest
+from ...models.manifest import Description, Document, Manifest
 from ...utils.contextmgr import PersistentOnErrorTemporaryDirectory, edit_json
 from ...utils.git import ManagedGitRepo
 from ..context import DocBuildContext
@@ -338,21 +338,24 @@ def store_productdocset_json(
 
     for doctype, docset, files in collect_files_flat(doctypes, meta_cache_dir):
         # files: list[Path]
+        # TODO: Create a Deliverable object?
         product = doctype.product.value
         stdout.print(f" > Processed group: {doctype} / {docset}")
         # The XPath logic is encapsulated within the Doctype model
         productxpath = f"./{doctype.product_xpath_segment()}"
         productnode = stitchnode.find(productxpath)
         docsetxpath = f"./{doctype.docset_xpath_segment(docset)}"
         docsetnode = productnode.find(docsetxpath)
+        descriptions = list(Description.from_xml_node(productnode))
 
         manifest = Manifest(
             productname=productnode.find("name").text,
             acronym=product,
             version=docset,
             lifecycle=docsetnode.attrib.get("lifecycle") or "",
+            descriptions=descriptions,
             # * hide-productname is False by default in the Manifest model
-            # * descriptions, categories, archives are empty lists by default
+            # * archives are empty lists by default
         )
 
         for f in files:
@@ -384,6 +387,8 @@ def store_productdocset_json(
         jsonfile = (
             jsondir / f"{docset}.json"
         )  # e.g., /path/to/cache/product_id/docset_id.json
+
+        #
         jsonfile.write_text(manifest.model_dump_json(indent=2, by_alias=True))
         log.info(
             "Wrote merged metadata JSON for %s/%s => %s", product, docset, jsonfile
diff --git a/src/docbuild/models/deliverable.py b/src/docbuild/models/deliverable.py
@@ -1,5 +1,6 @@
 """Module for defining the Deliverable model."""
 
+from collections.abc import Generator
 from dataclasses import dataclass, field
 from functools import cached_property
 from pathlib import Path
@@ -28,6 +29,43 @@ class Deliverable:
     _product_node: etree._Element | None = field(repr=False, default=None)
     _meta: Metadata | None = None
 
+    @cached_property
+    def all_categories(self) -> Generator[etree._Element, None, None]:
+        """Return the groups (formerly categories) of the deliverable.
+
+        Yield all elements from the product and root node.
+
+        :yield: The elements categories/category and category.
+        """
+        yield from self.categories
+        yield from self.categories_from_root
+
+    @cached_property
+    def categories(self) -> Generator[etree._Element, None, None]:
+        """Return the groups (formerly categories) from the product node.
+
+        Yield all elements under the product were this deliverable belongs to.
+
+        :yield: The elements categories/category and category.
+        """
+        yield from self.product_node.xpath("categories/category|category")
+
+    @cached_property
+    def categories_from_root(self) -> Generator[etree._Element, None, None]:
+        """Return the groups (formerly categories) from the root node.
+
+        Yield all elements under the root node.
+
+        :yield: The elements categories/category and category.
+        """
+        root = self.product_node.getroottree().getroot()
+        yield from root.xpath("categories/category|category")
+
+    @cached_property
+    def desc(self) -> Generator[etree._Element, None, None]:
+        """Return the <desc> from the product node."""
+        yield from self.product_node.xpath("desc")
+
     @cached_property
     def productid(self) -> str | None:
         """Return the product ID."""
diff --git a/src/docbuild/models/manifest.py b/src/docbuild/models/manifest.py
diff --git a/tests/models/test_deliverable.py b/tests/models/test_deliverable.py
diff --git a/tests/models/test_manifest.py b/tests/models/test_manifest.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Add serialization of missing :class:`~docserv.models.deliverable.Description`.