nfpm: Improve field doc rendering on website (#21807)

The formatting of the nfpm field documentation was slightly mangled on the website. This is an attempt to improve that.
pantsbuild · Jan 2, 2025 · 8a3173e · 8a3173e
1 parent f70f715
commit 8a3173e
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 97 deletions.
diff --git a/src/python/pants/backend/nfpm/fields/all.py b/src/python/pants/backend/nfpm/fields/all.py
@@ -106,7 +106,7 @@ class NfpmArchField(StringField):
         https://nfpm.goreleaser.com/goarch-to-pkg/
 
         Use one of these values unless you need nFPM to use your value as-is:
-        {", ".join(repr(arch.value) for arch in NfpmArch.__members__.values())}
+        `{" | ".join(repr(arch.value) for arch in NfpmArch.__members__.values())}`
         """
     )
 

diff --git a/src/python/pants/backend/nfpm/fields/apk.py b/src/python/pants/backend/nfpm/fields/apk.py
@@ -58,9 +58,9 @@ class NfpmApkReplacesField(NfpmPackageRelationshipsField):
 
         This field takes a simple list of package names, like this:
 
-        - "bash"
-        - "git"
-        - "pkgconfig"
+          - "bash"
+          - "git"
+          - "pkgconfig"
 
         See:
         https://wiki.alpinelinux.org/wiki/Apk_spec#PKGINFO_Format
@@ -91,14 +91,14 @@ class NfpmApkProvidesField(NfpmPackageRelationshipsField):
 
         Here are some examples extracted a variety of random packages:
 
-        - "cmd:bash=5.2.15-r0"
-        - "cmd:git=2.38.5-r0"
-        - "cmd:gio=2.74.6-r0"
-        - "so:libgio-2.0.so.0=0.7400.6"
-        - "so:libglib-2.0.so.0=0.7400.6"
-        - "py3.10:pkgconfig=1.5.5-r1"
-        - "pc:libpkgconf=1.9.4"
-        - "pkgconfig=1"
+          - "cmd:bash=5.2.15-r0"
+          - "cmd:git=2.38.5-r0"
+          - "cmd:gio=2.74.6-r0"
+          - "so:libgio-2.0.so.0=0.7400.6"
+          - "so:libglib-2.0.so.0=0.7400.6"
+          - "py3.10:pkgconfig=1.5.5-r1"
+          - "pc:libpkgconf=1.9.4"
+          - "pkgconfig=1"
 
         See:
         https://wiki.alpinelinux.org/wiki/Apk_spec#PKGINFO_Format
@@ -138,19 +138,19 @@ class NfpmApkDependsField(NfpmPackageRelationshipsField):
 
         Example package dependencies (which do not have a prefix):
 
-        - "git"
-        - "git=2.40.1-r0"
+          - "git"
+          - "git=2.40.1-r0"
 
         Example absolute path dependencies (which start with `/`):
 
-        - "/bin/sh"
+          - "/bin/sh"
 
         Example shared object dependencies (which have a `so:` prefix):
 
-        - "so:libc.musl-x86_64.so.1"
-        - "so:libcurl.so.4"
-        - "so:libpcre2-8.so.0"
-        - "so:libz.so.1"
+          - "so:libc.musl-x86_64.so.1"
+          - "so:libcurl.so.4"
+          - "so:libpcre2-8.so.0"
+          - "so:libz.so.1"
 
         WARNING: This is NOT the same as the 'dependencies' field!
         It does not accept pants-style dependencies like target addresses.
@@ -187,14 +187,14 @@ class NfpmApkScriptsField(NfpmPackageScriptsField):
         The script types are the terms used by nFPM. For reference, Alpine Linux
         uses the following terms in the APKBUILD file instead:
 
-            | nFPM term   | APKBUILD term  |
-            +-------------+----------------+
-            | preinstall  | pre-install    |
-            | postinstall | post-install   |
-            | preupgrade  | pre-upgrade    |
-            | postupgrade | post-upgrade   |
-            | preremove   | pre-deinstall  |
-            | postremove  | post-deinstall |
+        | nFPM term   | APKBUILD term  |
+        +-------------+----------------+
+        | preinstall  | pre-install    |
+        | postinstall | post-install   |
+        | preupgrade  | pre-upgrade    |
+        | postupgrade | post-upgrade   |
+        | preremove   | pre-deinstall  |
+        | postremove  | post-deinstall |
 
         Please consult the Alpine Linux docs to understand when `apk` will run
         each of these scripts, how it handles a failure, and what failure means

diff --git a/src/python/pants/backend/nfpm/fields/archlinux.py b/src/python/pants/backend/nfpm/fields/archlinux.py
@@ -107,9 +107,9 @@ class NfpmArchlinuxProvidesField(NfpmPackageRelationshipsField):
         Because the "baz" package implicitly provides its own name, this list
         should not include "baz".
 
-        - "foo"
-        - "bar=1.0.0"
-        - "libbaz.so=2"
+          - "foo"
+          - "bar=1.0.0"
+          - "libbaz.so=2"
 
         If several packages declare the same '{NfpmArchlinuxProvidesField.alias}',
         then they might need to declare that they conflict with each other
@@ -140,9 +140,9 @@ class NfpmArchlinuxDependsField(NfpmPackageRelationshipsField):
         The '{NfpmArchlinuxDependsField.alias}' field has install-time dependencies
         that can use version selectors (with one of `<`, `<=`, `=`, `>=`, `>`).
 
-        - "git"
-        - "tcpdump<5"
-        - "foobar>=1.8.0"
+          - "git"
+          - "tcpdump<5"
+          - "foobar>=1.8.0"
 
         WARNING: This is NOT the same as the 'dependencies' field!
         It does not accept pants-style dependencies like target addresses.
@@ -192,14 +192,14 @@ class NfpmArchlinuxScriptsField(NfpmPackageScriptsField):
         by adding a shell function for each of your script files where your script becomes
         the body of that function. These functions are:
 
-            | nFPM script | `.INSTALL` function |
-            +-------------+---------------------+
-            | preinstall  | pre_install         |
-            | postinstall | post_install        |
-            | preupgrade  | pre_upgrade         |
-            | postupgrade | post_upgrade        |
-            | preremove   | pre_remove          |
-            | postremove  | post_remove         |
+        | nFPM script | `.INSTALL` function |
+        +-------------+---------------------+
+        | preinstall  | pre_install         |
+        | postinstall | post_install        |
+        | preupgrade  | pre_upgrade         |
+        | postupgrade | post_upgrade        |
+        | preremove   | pre_remove          |
+        | postremove  | post_remove         |
 
         So, if you provide a `preinstall` script, the `.INSTALL` scriptlet would contain:
 

diff --git a/src/python/pants/backend/nfpm/fields/contents.py b/src/python/pants/backend/nfpm/fields/contents.py
@@ -127,21 +127,21 @@ class NfpmContentFileModeField(IntField):
         For example to specify world readable/executable and user writable, these
         are equivalent:
 
-        - `0o755`
-        - `'755'`
-        - `'rwxr-xr-x'`
+          - `0o755`
+          - `'755'`
+          - `'rwxr-xr-x'`
 
         Another example for a file with read/write permissions for only the user:
 
-        - `0o600`
-        - `'600'`
-        - `'rw-------'`
+          - `0o600`
+          - `'600'`
+          - `'rw-------'`
 
         Another example for a file with the group sticky bit set:
 
-        - `0o2660`
-        - `'2660'`
-        - `'rw-rwS---'`
+          - `0o2660`
+          - `'2660'`
+          - `'rw-rwS---'`
 
         WARNING: If you forget to include the `0o` prefix on a numeric octal, then
         it will be interpreted as an integer which is probably not what you want.

diff --git a/src/python/pants/backend/nfpm/fields/deb.py b/src/python/pants/backend/nfpm/fields/deb.py
@@ -200,8 +200,8 @@ class NfpmDebProvidesField(NfpmPackageRelationshipsField):
 
         For example, these declare virtual packages foo and bar.
 
-        - "foo"
-        - "bar (=1.0.0)"
+          - "foo"
+          - "bar (=1.0.0)"
 
         If several packages declare the same '{NfpmDebProvidesField.alias}',
         then they might need to declare that they conflict with each other
@@ -225,9 +225,9 @@ class NfpmDebDependsField(NfpmPackageRelationshipsField):
         in parentheses) or use `|` to specify package alternatives that equally
         satisfy a dependency.
 
-        - "git"
-        - "libc6 (>= 2.2.1)"
-        - "default-mta | mail-transport-agent"
+          - "git"
+          - "libc6 (>= 2.2.1)"
+          - "default-mta | mail-transport-agent"
 
         Make sure to include package dependencies of this package as well as any
         packages required by the `postinstall`, `postupgrade`, or `preremove` scripts.
@@ -314,8 +314,8 @@ class NfpmDebConflictsField(NfpmPackageRelationshipsField):
         foo (version 2.5 or less) and bar packages, so they must be uninstalled
         before this package can be installed.
 
-        - "foo (<2.6)"
-        - "bar"
+          - "foo (<2.6)"
+          - "bar"
 
         See: https://www.debian.org/doc/debian-policy/ch-relationships.html#conflicting-binary-packages-conflicts
         """
@@ -341,8 +341,8 @@ class NfpmDebBreaksField(NfpmPackageRelationshipsField):
         only if foo version 2.5 or less is installed and it breaks package bar
         no matter what version is installed.
 
-        - "foo (<2.6)"
-        - "bar"
+          - "foo (<2.6)"
+          - "bar"
 
         See: https://www.debian.org/doc/debian-policy/ch-relationships.html#packages-which-break-other-packages-breaks
         """
@@ -388,15 +388,15 @@ class NfpmDebScriptsField(NfpmPackageScriptsField):
         The script types are the names used by nFPM. For reference, Debian
         uses the following file names instead:
 
-            | nFPM script | Debian file |
-            +-------------+-------------+
-            | preinstall  | preinst     |
-            | postinstall | postinst    |
-            | preremove   | prerm       |
-            | postremove  | postrm      |
-            | config      | config      |
-            | templates   | templates   |
-            | rules       | rules       |
+        | nFPM script | Debian file |
+        +-------------+-------------+
+        | preinstall  | preinst     |
+        | postinstall | postinst    |
+        | preremove   | prerm       |
+        | postremove  | postrm      |
+        | config      | config      |
+        | templates   | templates   |
+        | rules       | rules       |
 
         The `pre*` and `post*` scripts are used by `dpkg` at various stages of
         installing, upgrading, and removing the deb package.

diff --git a/src/python/pants/backend/nfpm/fields/rpm.py b/src/python/pants/backend/nfpm/fields/rpm.py
@@ -158,9 +158,9 @@ class NfpmRpmProvidesField(NfpmPackageRelationshipsField):
         The list can include virtual package names and/or file paths. For example
         the `bash` package includes these in '{NfpmRpmProvidesField.alias}':
 
-        - "bash"
-        - "/bin/sh"
-        - "/bin/bash"
+          - "bash"
+          - "/bin/sh"
+          - "/bin/bash"
 
         This means another package could also provide alternative implementations for
         the "bash" package name and could provide "/bin/sh" and/or "/bin/bash".
@@ -185,9 +185,9 @@ class NfpmRpmDependsField(NfpmPackageRelationshipsField):
         use version selectors (with one of `<`, `<=`, `=`, `>=`, `>` surrounded by
         spaces), where the version is formatted: `[epoch:]version[-release]`
 
-        - "git"
-        - "bash < 5"
-        - "perl >= 9:5.00502-3"
+          - "git"
+          - "bash < 5"
+          - "perl >= 9:5.00502-3"
 
         The rpm file header uses the term "requires" for this. This field is
         named "{NfpmRpmDependsField.alias}" because that is the term used by nFPM.
@@ -290,24 +290,24 @@ class NfpmRpmCompressionField(StringField):
         Here are several gzip examples with and without the optional compression level
         (-1 means use the default level which is 5; 9 is the max).
 
-        '{NfpmRpmCompressionAlgorithm.gzip.value}:9'
-        '{NfpmRpmCompressionAlgorithm.gzip.value}:0'
-        '{NfpmRpmCompressionAlgorithm.gzip.value}:-1'
-        '{NfpmRpmCompressionAlgorithm.gzip.value}:5'
-        '{NfpmRpmCompressionAlgorithm.gzip.value}'
+          - '{NfpmRpmCompressionAlgorithm.gzip.value}:9'
+          - '{NfpmRpmCompressionAlgorithm.gzip.value}:0'
+          - '{NfpmRpmCompressionAlgorithm.gzip.value}:-1'
+          - '{NfpmRpmCompressionAlgorithm.gzip.value}:5'
+          - '{NfpmRpmCompressionAlgorithm.gzip.value}'
 
         Here are several zstd examples. Note that nFPM uses a library that  only
         defines four named compression levels, and then maps the zstd integer
         levels to those. You may specify the zstd level as an integer, or using
         these names: https://github.com/klauspost/compress/tree/master/zstd#status
 
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:fastest'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:default'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:better'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:best'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:3'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}:9'
-        '{NfpmRpmCompressionAlgorithm.zstd.value}'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:fastest'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:default'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:better'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:best'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:3'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}:9'
+          - '{NfpmRpmCompressionAlgorithm.zstd.value}'
         """
     )
 
@@ -368,15 +368,15 @@ class NfpmRpmScriptsField(NfpmPackageScriptsField):
         uses the following scriptlet tag names instead and runs them before/after
         the indicated phase:
 
-            | nFPM term   | RPM scriptlet | RPM phase   |
-            +-------------+---------------+-------------+
-            | preinstall  | %pre          | install     |
-            | postinstall | %post         | install     |
-            | preremove   | %preun        | uninstall   |
-            | postremove  | %postun       | uninstall   |
-            | pretrans    | %pretrans     | transaction |
-            | posttrans   | %posttrans    | transaction |
-            | verify      | %verifyscript | verify      |
+        | nFPM term   | RPM scriptlet | RPM phase   |
+        +-------------+---------------+-------------+
+        | preinstall  | %pre          | install     |
+        | postinstall | %post         | install     |
+        | preremove   | %preun        | uninstall   |
+        | postremove  | %postun       | uninstall   |
+        | pretrans    | %pretrans     | transaction |
+        | posttrans   | %posttrans    | transaction |
+        | verify      | %verifyscript | verify      |
 
         Please consult the RPM docs to understand what is required of these scripts.
 
@@ -396,8 +396,8 @@ class NfpmRpmGhostContents(StringSequenceField):
         A list of files that this package owns, but that this package does not include.
 
         Examples of ghosted files include:
-        - A log file or a state file that does not exist until runtime.
-        - A binary that is managed by 'alternatives'.
+          - A log file or a state file that does not exist until runtime.
+          - A binary that is managed by 'alternatives'.
 
         RPM specs use the `%ghost` directive to list these ghosted files.