Rewrite the Quadlet documentation. #26929

jankaluza · 2025-08-29T10:56:42Z

This commit does the following:

Splits the podman-systemd.unit.5.md into multiple files - one for each quadlet file type, podman-quadlet.7.md for general quadlet information and podman-quadlet-basic-usage.7.md for quadlet examples.
Removes the original podman-systemd.unit.5.md file.
Adds support for jinja2 templating language in the markdown_preprocess.
Uses jinja2 in options/*.md to use the single .md file for both podman subcommands man-pages and quadlet man-pages. This deduplicates the Quadlet man-pages a lot.
Adds new @@option quadlet:source.md preprocess command to import such .md files from options directory.

Does this PR introduce a user-facing change?

None

openshift-ci · 2025-08-29T10:56:49Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: jankaluza
Once this PR has been reviewed and has the lgtm label, please assign lsm5 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

packit-as-a-service · 2025-08-29T10:59:02Z

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

@option

This commit does the following: - Splits the podman-systemd.unit.5.md into multiple files - one for each quadlet file type, podman-quadlet.7.md for general quadlet information and podman-quadlet-basic-usage.7.md for quadlet examples. - Removes the original podman-systemd.unit.5.md file. - Adds support for jinja2 templating language in the markdown_preprocess. - Uses jinja2 in options/*.md to use the single .md file for both podman subcommands man-pages and quadlet man-pages. This deduplicates the Quadlet man-pages a lot. - Adds new `@@option quadlet:source.md` preprocess command to import such .md files from options directory. Signed-off-by: Jan Kaluza <[email protected]>

Luap99

not a proper review just some drive by comments

Luap99 · 2025-08-29T11:54:49Z

hack/markdown-preprocess

@@ -11,6 +11,7 @@ import glob
 import os
 import re
 import sys
+from jinja2 import Template


jinja2 is not in the std lib, which means we somehow much install it it everywhere the preprocessor runs (including the redthedocs build process)

podman/docs/source/conf.py

Line 32 in 07bb670

path = os.path.join(os.path.abspath(os.path.dirname(

While I really like the de duplication I think maybe it would be better if we can avoid jinja2?

Yeah. I was thinking about extending the existing parser in some way, but to be honest doing my own if-logic in python seems like reinventing the wheel. I was also playing with some other syntax ideas, but they looked like one big hack in the end.

I will check it back on Monday when fresh to see if I get better idea.

yeah I agree the current way is a ugly and horrible. having a proper template engine might be better.
But I do really wonder if hand rolling our own thing even when using a custom template is the right thing? I think there must be better doc generation tools existing already somewhere that could be used instead. I know it would be a lot of work and maybe outside of the scope for this but maybe it would be better to write our docs in rst where we can have proper includes instead of this markdown hacking

Luap99 · 2025-08-29T11:58:54Z

docs/source/markdown/podman-systemd.unit.5.md

Let's do not remove this, there are endless of people linking that page or are used to typing man podman-systemd.unit that we break with this.

IMO the podman-quadlet content should be in this file instead and we should not have a second podman-quadlet man page which is confusing when there is both a .1 and .7 file

OK. That's good point. I will update it.

Luap99 · 2025-08-29T11:59:27Z

docs/source/markdown/podman-quadlet.7.md

+- **`.container`** — Defines and manages a single container. See **podman-container.unit(5)**.
+- **`.pod`** — Creates a Podman pod that containers can join. See **podman-pod.unit(5)**.
+- **`.volume`** — Ensures a named Podman volume exists. See **podman-volume.unit(5)**.
+- **`.network`** — Creates a Podman network for containers and pods. See **podman-network.unit(5)**.
+- **`.image`** — Pulls and caches a container image. See **podman-image.unit(5)**.
+- **`.build`** — Builds a container image from a Containerfile. See **podman-build.unit(5)**.
+- **`.kube`** — Deploys containers from Kubernetes YAML using `podman kube play`. See **podman-kube.unit(5)**.


these should all be actual links so users can click on the on the website

Luap99 · 2025-08-29T12:00:23Z

docs/source/markdown/podman-image.unit.5.md.in

+## Quadlet section [Quadlet]
+Some quadlet specific configuration is shared between different unit types. Those settings
+can be configured in the `[Quadlet]` section.
+
+Valid options for `[Quadlet]` are listed below:
+
+| **[Quadlet] options**      | **Description**                                   |
+|----------------------------|---------------------------------------------------|
+| DefaultDependencies=false  | Disable implicit network dependencies to the unit |
+
+### `DefaultDependencies=`
+
+Add Quadlet's default network dependencies to the unit (default is `true`).
+
+When set to false, Quadlet will **not** add a dependency (After=, Wants=) to
+`network-online.target`/`podman-user-wait-network-online.service` to the generated unit.
+
+Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section
+has an option with the same name but a different meaning.


That is a global section supported by all file types so it should be documented in podman-systemd.unit

Luap99 · 2025-08-29T12:01:36Z

docs/source/markdown/podman-build.unit.5.md.in

+# FILE LOCATIONS
+
+Place `.build` files in one of the following:
+
+### Rootless
+
+- `$XDG_RUNTIME_DIR/containers/systemd/`
+- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
+- `/etc/containers/systemd/users/$(UID)`
+- `/etc/containers/systemd/users/`
+
+### Rootful
+
+- `/run/containers/systemd/`
+- `/etc/containers/systemd/`
+- `/usr/share/containers/systemd/`
+


That is duplication you have in any file, IMO it is enough to document this only once in the main file

baude · 2025-08-29T13:53:11Z

docs/source/markdown/podman-image.unit.5.md.in

+
+```
+[Image]
+Image=quay.io/centos/centos:latest


he example here made me think ... earlier you mentioned that people should use fully qualified names for performance. I would argue it is for security as much as anything. And that said, upon seeing this, I wondered if we should also be recommending, generally, that people use a tagged image instead of latest to avoid things changing underneath them? Just a thought (oh, an apologies if i missed it or its somewhere where i havent reviewed yet)

baude · 2025-08-29T13:53:53Z

docs/source/markdown/podman-kube.unit.5.md.in

+# SEE ALSO
+
+[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html),
+[podman-kube-play(1)](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html),


should kube-generate be in here?

baude · 2025-08-29T15:27:12Z

did a quick pass like @Luap99 ... looks like you need to repush at least to fix validate issues. @ygalblum do you think you could also spend a little time reviewing this large PR?

eriksjolund · 2025-08-29T19:04:19Z

docs/source/markdown/options/gidmap.container.md


-Run the container in a new user namespace using the supplied GID mapping. This
-option conflicts with the **--userns** and **--subgidname** options. This
+un the container in a new user namespace using the supplied GID mapping. This


typo:
un the container -> Run the container

eriksjolund · 2025-08-29T19:07:05Z

docs/source/markdown/options/gidmap.container.md


-Run the container in a new user namespace using the supplied GID mapping. This
-option conflicts with the **--userns** and **--subgidname** options. This
+un the container in a new user namespace using the supplied GID mapping. This


typo:
un the container -> Run the container

openshift-merge-robot · 2025-09-02T09:44:47Z

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

Signed-off-by: Jan Kaluza <[email protected]>

openshift-ci bot added the release-note-none label Aug 29, 2025

jankaluza force-pushed the quadlet-docs branch from 8558e91 to 6612832 Compare August 29, 2025 10:58

jankaluza force-pushed the quadlet-docs branch 3 times, most recently from c55dc16 to 534eb3f Compare August 29, 2025 11:33

jankaluza force-pushed the quadlet-docs branch from 534eb3f to e7916da Compare August 29, 2025 11:47

Luap99 reviewed Aug 29, 2025

View reviewed changes

baude reviewed Aug 29, 2025

View reviewed changes

eriksjolund reviewed Aug 29, 2025

View reviewed changes

openshift-merge-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 2, 2025

Change the syntax to not depend on jinja2.

1574d55

Signed-off-by: Jan Kaluza <[email protected]>

Rewrite the Quadlet documentation. #26929

Are you sure you want to change the base?

Rewrite the Quadlet documentation. #26929

Conversation

jankaluza commented Aug 29, 2025

Does this PR introduce a user-facing change?

Uh oh!

openshift-ci bot commented Aug 29, 2025

Uh oh!

packit-as-a-service bot commented Aug 29, 2025

Uh oh!

Luap99 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

baude commented Aug 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-merge-robot commented Sep 2, 2025

Uh oh!

Uh oh!