WIP: Add serialization of missing Description

tomschr · tomschr · commit 63d3746aef83 · 2026-02-03T21:27:51.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/constants/index.rst b/docs/source/reference/_autoapi/docbuild/constants/index.rst
@@ -19,6 +19,7 @@ Attributes
    docbuild.constants.ALLOWED_LANGUAGES
    docbuild.constants.DEFAULT_DELIVERABLES
    docbuild.constants.SERVER_ROLES
+   docbuild.constants.SERVER_ROLES_ALIASES
    docbuild.constants.DEFAULT_LIFECYCLE
    docbuild.constants.ALLOWED_LIFECYCLES
    docbuild.constants.VALID_PRODUCTS
@@ -74,7 +75,14 @@ Module Contents
 
 .. py:data:: SERVER_ROLES
 
-   The different server roles, including long and short spelling.
+   The unique primary server role values.
+
+
+.. py:data:: SERVER_ROLES_ALIASES
+   :value: ('PRODUCTION', 'STAGING', 'TESTING', 'PROD', 'P', 'prod', 'p', 'STAGE', 'S', 'stage', 's',...
+
+
+   All valid server role names and aliases for validation and testing.
 
 
 .. py:data:: DEFAULT_LIFECYCLE
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/doctype/Doctype.rst b/docs/source/reference/_autoapi/docbuild/models/doctype/Doctype.rst
@@ -125,14 +125,6 @@ docbuild.models.doctype.Doctype
 
 
 
-   .. py:method:: coerce_lifecycle(value: str | docbuild.models.lifecycle.LifecycleFlag) -> docbuild.models.lifecycle.LifecycleFlag
-      :classmethod:
-
-
-      Convert a string into a LifecycleFlag.
-
-
-
    .. py:method:: coerce_langs(value: str | list[str | docbuild.models.language.LanguageCode]) -> list[docbuild.models.language.LanguageCode]
       :classmethod:
 
@@ -166,3 +158,19 @@ docbuild.models.doctype.Doctype
           deliverables that match this Doctype.
 
 
+
+   .. py:method:: product_xpath_segment() -> str
+
+      Return the XPath segment for the product node.
+
+      Example: "product[@productid='sles']" or "product"
+
+
+
+   .. py:method:: docset_xpath_segment(docset: str) -> str
+
+      Return the XPath segment for the docset node.
+
+      Example: "docset[@setid='15-SP6']" or "docset"
+
+
diff --git a/docs/source/reference/_autoapi/docbuild/models/index.rst b/docs/source/reference/_autoapi/docbuild/models/index.rst
@@ -20,6 +20,7 @@ Submodules
    /reference/_autoapi/docbuild/models/doctype/index
    /reference/_autoapi/docbuild/models/language/index
    /reference/_autoapi/docbuild/models/lifecycle/index
+   /reference/_autoapi/docbuild/models/manifest/index
    /reference/_autoapi/docbuild/models/metadata/index
    /reference/_autoapi/docbuild/models/path/index
    /reference/_autoapi/docbuild/models/product/index
diff --git a/docs/source/reference/_autoapi/docbuild/models/lifecycle/LifecycleFlag.rst b/docs/source/reference/_autoapi/docbuild/models/lifecycle/LifecycleFlag.rst
@@ -44,7 +44,7 @@ docbuild.models.lifecycle.LifecycleFlag
 
 
 
-   .. py:method:: from_str(value: str) -> LifecycleFlag
+   .. py:method:: from_str(value: str) -> Self
       :classmethod:
 
 
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/docs/source/reference/_autoapi/docbuild/models/serverroles/ServerRole.rst b/docs/source/reference/_autoapi/docbuild/models/serverroles/ServerRole.rst
@@ -11,27 +11,5 @@ docbuild.models.serverroles.ServerRole
 
    The server role.
 
-
-   .. py:attribute:: PRODUCTION
-      :value: 'production'
-
-
-      Server is in production mode, serving live traffic.
-
-
-
-   .. py:attribute:: STAGING
-      :value: 'staging'
-
-
-      Server is in staging mode, used for testing before production.
-
-
-
-   .. py:attribute:: TESTING
-      :value: 'testing'
-
-
-      Server is in testing mode, used for development and QA.
-
+   This Enum supports various aliases and case variations for each role.
 
diff --git a/src/docbuild/cli/cmd_metadata/metaprocess.py b/src/docbuild/cli/cmd_metadata/metaprocess.py
diff --git a/src/docbuild/models/deliverable.py b/src/docbuild/models/deliverable.py
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`.
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@ docbuild.models.lifecycle.LifecycleFlag`
`44`	`44`
`45`	`45`
`46`	`46`
`47`		`- .. py:method:: from_str(value: str) -> LifecycleFlag`
	`47`	`+ .. py:method:: from_str(value: str) -> Self`
`48`	`48`	`:classmethod:`
`49`	`49`
`50`	`50`