From 3a9a3c81a34f54bfdf10fce7002f11d6628f4b39 Mon Sep 17 00:00:00 2001 From: guillermodotn Date: Thu, 2 Apr 2026 10:55:52 +0000 Subject: [PATCH 1/4] doc: add treeinfo 1.2 file format documentation Assisted-by: Claude Opus --- doc/index.rst | 3 +- doc/treeinfo-1.2.rst | 107 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 doc/treeinfo-1.2.rst diff --git a/doc/index.rst b/doc/index.rst index ce87aa2..e75162a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,7 +35,7 @@ File formats: discinfo-1.0 images-1.1 rpms-1.1 - treeinfo-1.1 + treeinfo-1.2 Old file formats: @@ -45,6 +45,7 @@ Old file formats: composeinfo-1.0 images-1.0 rpms-1.0 + treeinfo-1.1 treeinfo-1.0 diff --git a/doc/treeinfo-1.2.rst b/doc/treeinfo-1.2.rst new file mode 100644 index 0000000..881ea08 --- /dev/null +++ b/doc/treeinfo-1.2.rst @@ -0,0 +1,107 @@ +======================== +Treeinfo file format 1.2 +======================== + +Treeinfo files provide details about installable trees in Fedora composes and media. + + +Changes from 1.1 +================= + +The treeinfo file format is unchanged from 1.1. +The version was bumped to 1.2 due to changes in other metadata files +(``images.json`` no longer allows ``src`` as a standalone architecture; +source images are stored under binary architectures instead). + + +File Format +=========== + +Treeinfo is an INI file. +It's recommended to sort sections and keys alphabetically +in order to diff .treeinfo files easily. + +:: + + [header] + type = ; metadata type; "productmd.treeinfo" required; [new in 1.1] + version = 1.2 ; metadata version; format: $major.$minor + + [release] + name = ; release name, for example: "Fedora", "Red Hat Enterprise Linux", "Spacewalk" + short = ; release short name, for example: "F", "RHEL", "Spacewalk" + version = ; release version, for example: "21", "7.0", "2.1" + type = ; release type, for example: "ga", "updates", "eus"; [new in 1.1] + is_layered = ; typically False for an operating system, True otherwise + + [base_product] + name = ; base product name, for example: "Fedora", "Red Hat Enterprise Linux" + short = ; base product short name, for example: "F", "RHEL" + version = ; base product *major* version, for example: "21", "7" + type = ; base product release type, for example: "ga", "eus"; [new in 1.1] + + [tree] + arch = ; tree architecture, for example x86_64 + build_timestamp = ; tree build time timestamp; format: unix time + platforms = [, ...] ; supported platforms; for example x86_64,xen + variants = [, ...] ; UIDs of available variants, for example "Server,Workstation" + + [checksums] + ; checksums of selected files in a tree: + ; * all repodata/repomd.xml + ; * all images captured in [images-*] and [stage2] sections + $path = $checksum_type:checksum_value + + [images-$platform] + ; images compatible with particular $platform + $file_name = $relative_path + + [stage2] + ; optional section, available only on bootable media with Anaconda installer + instimage = ; relative path to Anaconda instimage (obsolete) + mainimage = ; relative path to Anaconda stage2 image + + [media] + ; optional section, available only on media + discnum = ; disc number + totaldiscs = ; number of discs in media set + + [variant-$variant_uid] + id = ; variant ID + uid = ; variant UID ($parent_UID.$ID) + name = ; variant name + type = ; variant, optional + variants = [,...] ; UIDs of child variants + addons = [,...] ; UIDs of child addons + + ; variant paths + ; all paths are relative to .treeinfo location + packages = ; directory with binary RPMs + repository = ; YUM repository with binary RPMs + source_packages = ; directory with source RPMs + source_repository = ; YUM repository with source RPMs + debug_packages = ; directory with debug RPMs + debug_repository = ; YUM repository with debug RPMs + identity = ; path to a pem file that identifies a product + + [addon-$addon_uid] + id = ; addon ID + uid = ; addon UID ($parent_UID.$ID) + name = ; addon name + type = addon + + ; addon paths + ; see variant paths + + [general] + ; WARNING.0 = This section provides compatibility with pre-productmd treeinfos. + ; WARNING.1 = Read productmd documentation for details about new format. + family = ; equal to [release]/name + version = ; equal to [release]/version + name = ; equal to "$family $version" + arch = ; equal to [tree]/arch + platforms = [,...] ; equal to [tree]/platforms + packagedir = ; equal to [variant-*]/packages + repository = ; equal to [variant-*]/repository + timestamp = ; equal to [tree]/build_timestamp + variant = ; variant UID of first variant (sorted alphabetically) From afa7db00dc48e6ee1d17e1c9cebd9bad3816b695 Mon Sep 17 00:00:00 2001 From: guillermodotn Date: Fri, 6 Mar 2026 15:03:34 +0100 Subject: [PATCH 2/4] Doc/man build pipeline. --- .github/workflows/docs.yml | 42 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..d8e86ae --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,42 @@ +name: Docs + +on: + push: + paths: + - "doc/**" + - "productmd/**" + - ".github/workflows/docs.yml" + pull_request: + paths: + - "doc/**" + - "productmd/**" + - ".github/workflows/docs.yml" + release: + types: [published] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v6 + + - name: Install uv and Python interpreter + uses: astral-sh/setup-uv@v7 + with: + version-file: ".python-version" + version: "0.9.26" + enable-cache: true + + - name: Install dependencies + run: uv sync --group docs + + - name: Build HTML docs + run: uv run sphinx-build -W -b html doc doc/_build/html + + - name: Build man pages + run: uv run sphinx-build -W -b man doc doc/_build/man From 05381d5a8ba4810a7aa999944af12aba1de67d5a Mon Sep 17 00:00:00 2001 From: guillermodotn Date: Thu, 2 Apr 2026 14:45:39 +0200 Subject: [PATCH 3/4] docs: add sphinx-rtd-theme to docs dependency group --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 9468124..6e019af 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,7 @@ coverage = [ ] docs = [ "sphinx", + "sphinx-rtd-theme", ] dev = [ { include-group = "test" }, From 12d500f69606b9285ca7798a937bdbfecca15746 Mon Sep 17 00:00:00 2001 From: guillermodotn Date: Fri, 6 Mar 2026 14:06:47 +0100 Subject: [PATCH 4/4] Fix doc warnings --- doc/images.rst | 1 - productmd/images.py | 10 ++++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/images.rst b/doc/images.rst index 9c2aaaf..1ac5d54 100644 --- a/doc/images.rst +++ b/doc/images.rst @@ -3,7 +3,6 @@ images -- Image metadata ======================== .. automodule:: productmd.images - :members: Classes ======= diff --git a/productmd/images.py b/productmd/images.py index 36c9c20..484a549 100644 --- a/productmd/images.py +++ b/productmd/images.py @@ -38,10 +38,12 @@ print(qcow2s) - # ... prints the set of qcow2 images in all our variants: - [, - , - ] + print(qcow2s) + + # ... prints the set of qcow2 images in all our variants: + # [, + # , + # ] """