Skip to contentSkip to conversation

btrfs-progs: fix documentation build errors

PATCH In review Anand Jain 2 participants 5 messages Nov 19, 2024 – Nov 28, 2024

Subsystems (2)
lore
Share & tools
lore

Anand Jain

author
#0 lore raw

cover btrfs-progs: fix documentation build errors

This patchset addresses documentation build issues related to link formatting, indentation, and target name handling.

Anand Jain (3):
btrfs-progs: fix doc compile error in CHANGES file
btrfs-progs: fix doc build issue caused by confusion between BTRFS_
and target
btrfs-progs: fix doc build errors correct hyperlink formatting

 CHANGES                              | 22 +++----
 Documentation/Kernel-by-version.rst  | 88 ++++++++++++++--------------
 Documentation/dev/On-disk-format.rst |  2 +-
 3 files changed, 56 insertions(+), 56 deletions(-)
Signature · 1 line
2.47.0
author
#1 lore raw

PATCH 1/3 btrfs-progs: fix doc compile error in CHANGES file

On python3-sphinx 7.2.6. and python3-sphinx_rtd_theme 2.0.0 there are build errors.

Making all in Documentation
[SPHINX] man
../CHANGES:26: ERROR: Unexpected indentation.
../CHANGES:29: WARNING: Block quote ends without a blank line; unexpected unindent. ../CHANGES:204: ERROR: Unexpected indentation.
../CHANGES:205: WARNING: Block quote ends without a blank line; unexpected unindent.

Fix them by adjusting the indentation in the CHANGES file. The sublist should be indented two spaces further than the main list.

---
 CHANGES                             | 22 +++++-----
 Documentation/Kernel-by-version.rst | 68 ++++++++++++++---------------
 2 files changed, 45 insertions(+), 45 deletions(-)
CHANGES +11 -11
index e2eed4b4390d..d7f326c450e1 100644
@@ -22,10 +22,10 @@ btrfs-progs-6.11 (2024-09-17)
 btrfs-progs-6.10 (2024-07-30)
 -----------------------------
    * inspect:
-     * list-chunks: new command to print information about chunks (i.e.
-       the physical chunks as stored on devices), sortable; requires root as
-       it's using SEARCH_TREE ioctl
-     * tree-stats:
+      * list-chunks: new command to print information about chunks (i.e.
+        the physical chunks as stored on devices), sortable; requires root as
+        it's using SEARCH_TREE ioctl
+      * tree-stats:
         * new option -t to print only the given tree
         * add long options for size units
    * filesystem df: with increased verbosity print per-type information from sysfs
@@ -199,13 +199,13 @@ btrfs-progs-6.6 (2023-11-03)
      future)
    * dump-tree: output sequence number for inline refs
    * fixes:
-     * fi resize: fallback to lowest devid when 1 does not exist, previously the
-       command would fail with "No such device"
-     * fi usage: fix "devices 0 != 1" message and broken output on multi-device
-       filesystem
-     * open files in non-blocking mode when reading fsid, this could hang when
-       trying to open fifo files or some special character devices, was observed
-       with 'prop set/get'
+      * fi resize: fallback to lowest devid when 1 does not exist, previously the
+        command would fail with "No such device"
+      * fi usage: fix "devices 0 != 1" message and broken output on multi-device
+        filesystem
+      * open files in non-blocking mode when reading fsid, this could hang when
+        trying to open fifo files or some special character devices, was observed
+        with 'prop set/get'
    * experimental:
       * mkfs: parametric zone size for emulated zoned mode
    * other:
Documentation/Kernel-by-version.rst +34 -34

92 lines not on this page · raw message

Signature · 1 line
2.47.0
author
#2 lore raw

PATCH 2/3 btrfs-progs: fix doc build issue caused by confusion between BTRFS_ and target

In reply to Anand Jain

Text ending with _ is treated as an anonymous hyperlink. Use an escape character \ to prevent this.

Making all in Documentation
[SPHINX] man
btrfs-progs/Documentation/dev/On-disk-format.rst:32: ERROR: Unknown target name: "btrfs".

---
 Documentation/dev/On-disk-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/dev/On-disk-format.rst +1 -1
index b3304032651b..39fdaf09b98b 100644
@@ -30,7 +30,7 @@ also contains a logical reference to root nodes in the root and chunk trees,
 which can then be used to locate all the other trees and data stored.
 
 To avoid duplicated suffixes/prefixes, sometimes the macro name will have
-the "BTRFS_" prefix and "_OBJECTID" suffix removed.
+the "BTRFS\_" prefix and "_OBJECTID" suffix removed.
 
 E.g. "BTRFS_DEV_ITEMS_OBJECTID" (0x1) can be shown as "DEV_ITEMS" for short,
 this matches the output of "btrfs inspect-internal dump-tree".
Signature · 1 line
2.47.0
author
#3 lore raw

PATCH 3/3 btrfs-progs: fix doc build errors correct hyperlink formatting

In reply to Anand Jain

Making all in Documentation
[SPHINX] man
Documentation/Kernel-by-version.rst:: ERROR: Anonymous hyperlink mismatch: 10 references but 0 targets. See "backrefs" attribute for IDs.
[PY] libbtrfsutil

The build is complaining about the missing space after (2) and <https:...>, as shown in the example below:

v6.10-rc3 (2)<https://git.kernel.org/linus/07978330e63456a75a6d5c1c5053de24bdc9d16f>__,

The compiler interprets this as a backref attribute. Add a space to make it render as text.

---
 Documentation/Kernel-by-version.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
Documentation/Kernel-by-version.rst +10 -10
index d1adc3ee6ebf..1066a8a22afd 100644
@@ -558,8 +558,8 @@ Fixes:
 ^^^^^^^^^^^^^^
 
 Pull requests:
-`v6.9-rc1 (1)<https://git.kernel.org/linus/43a7548e28a6df12a6170421d9d016c576010baa>`__,
-`v6.9-rc1 (2)<https://git.kernel.org/linus/7b65c810a1198b91ed6bdc49ddb470978affd122>`__,
+`v6.9-rc1 (1) <https://git.kernel.org/linus/43a7548e28a6df12a6170421d9d016c576010baa>`__,
+`v6.9-rc1 (2) <https://git.kernel.org/linus/7b65c810a1198b91ed6bdc49ddb470978affd122>`__,
 `v6.9-rc2 <https://git.kernel.org/linus/400dd456bda8be0b566f2690c51609ea02f85766>`__,
 `v6.9-rc3 <https://git.kernel.org/linus/20cb38a7af88dc40095da7c2c9094da3873fea23>`__,
 `v6.9-rc5 <https://git.kernel.org/linus/8cd26fd90c1ad7acdcfb9f69ca99d13aa7b24561>`__,
@@ -596,14 +596,14 @@ Other notable changes:
 ^^^^^^^^^^^^^^^
 
 Pull requests:
-`v6.10-rc1 (1)<https://git.kernel.org/linus/a3d1f54d7aa4c3be2c6a10768d4ffa1dcb620da9>`__,
-`v6.10-rc1 (2)<https://git.kernel.org/linus/02c438bbfffeabf8c958108f9cf88cdb1a11a323>`__,
-`v6.10-rc3 (1)<https://git.kernel.org/linus/19ca0d8a433ff37018f9429f7e7739e9f3d3d2b4>`__,
-`v6.10-rc3 (2)<https://git.kernel.org/linus/07978330e63456a75a6d5c1c5053de24bdc9d16f>`__,
+`v6.10-rc1 (1) <https://git.kernel.org/linus/a3d1f54d7aa4c3be2c6a10768d4ffa1dcb620da9>`__,
+`v6.10-rc1 (2) <https://git.kernel.org/linus/02c438bbfffeabf8c958108f9cf88cdb1a11a323>`__,
+`v6.10-rc3 (1) <https://git.kernel.org/linus/19ca0d8a433ff37018f9429f7e7739e9f3d3d2b4>`__,
+`v6.10-rc3 (2) <https://git.kernel.org/linus/07978330e63456a75a6d5c1c5053de24bdc9d16f>`__,
 `v6.10-rc5 <https://git.kernel.org/linus/50736169ecc8387247fe6a00932852ce7b057083>`__,
 `v6.10-rc6 <https://git.kernel.org/linus/66e55ff12e7391549c4a85a7a96471dcf891cb03>`__,
-`v6.10-rc7 (1)<https://git.kernel.org/linus/cfbc0ffea88c764d23f69efe6ecb74918e0f588e>`__,
-`v6.10-rc7 (2)<https://git.kernel.org/linus/661e504db04c6b7278737ee3a9116738536b4ed4>`__,
+`v6.10-rc7 (1) <https://git.kernel.org/linus/cfbc0ffea88c764d23f69efe6ecb74918e0f588e>`__,
+`v6.10-rc7 (2) <https://git.kernel.org/linus/661e504db04c6b7278737ee3a9116738536b4ed4>`__,
 `v6.10-rc8 <https://git.kernel.org/linus/975f3b6da18020f1c8a7667ccb08fa542928ec03>`__,
 
 Performance improvements:
@@ -632,8 +632,8 @@ Notable fixes or changes:
 ^^^^^^^^^^^^^^^
 
 Pull requests:
-`v6.11-rc1 (1)<https://git.kernel.org/linus/a1b547f0f217cfb06af7eb4ce8488b02d83a0370>`__,
-`v6.11-rc1 (2)<https://git.kernel.org/linus/53a5182c8a6805d3096336709ba5790d16f8c369>`__,
+`v6.11-rc1 (1) <https://git.kernel.org/linus/a1b547f0f217cfb06af7eb4ce8488b02d83a0370>`__,
+`v6.11-rc1 (2) <https://git.kernel.org/linus/53a5182c8a6805d3096336709ba5790d16f8c369>`__,
 `v6.11-rc2 <https://git.kernel.org/linus/e4fc196f5ba36eb7b9758cf2c73df49a44199895>`__,
 `v6.11-rc3 <https://git.kernel.org/linus/6a0e38264012809afa24113ee2162dc07f4ed22b>`__,
 `v6.11-rc4 <https://git.kernel.org/linus/1fb918967b56df3262ee984175816f0acb310501>`__,
Signature · 1 line
2.47.0
#4 lore raw
In reply to Anand Jain
Quoted 8 lines · Anand Jain

This patchset addresses documentation build issues related to link formatting, indentation, and target name handling.

Anand Jain (3):
btrfs-progs: fix doc compile error in CHANGES file
btrfs-progs: fix doc build issue caused by confusion between BTRFS_
and target
btrfs-progs: fix doc build errors correct hyperlink formatting

Added to devel, thanks.