[PATCH 0/3] btrfs-progs: fix documentation build errors

[PATCH 0/3] btrfs-progs: fix documentation build errors

[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

 CHANGES                              | 22 +++----
 Documentation/Kernel-by-version.rst  | 88 ++++++++++++++--------------
 Documentation/dev/On-disk-format.rst |  2 +-
 3 files changed, 56 insertions(+), 56 deletions(-)

-- 
2.47.0

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

[Anand Jain]

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.

Signed-off-by: Anand Jain <anand.jain@oracle.com>
---
 CHANGES                             | 22 +++++-----
 Documentation/Kernel-by-version.rst | 68 ++++++++++++++---------------
 2 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/CHANGES b/CHANGES
index e2eed4b4390d..d7f326c450e1 100644
--- a/CHANGES
+++ b/CHANGES
@@ -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:
diff --git a/Documentation/Kernel-by-version.rst b/Documentation/Kernel-by-version.rst
index c76a9c040115..d1adc3ee6ebf 100644
--- a/Documentation/Kernel-by-version.rst
+++ b/Documentation/Kernel-by-version.rst
@@ -512,20 +512,20 @@ Pull requests:
 Core changes:
 
 -  convert extent buffers to folios:
-   - direct API conversion where possible
-   - performance can drop by a few percent on metadata heavy
-     workloads, the folio sizes are not constant and the calculations
-     add up in the item helpers
-   - both regular and subpage modes
-   - data cannot be converted yet, we need to port that to iomap and
-     there are some other generic changes required
+    - direct API conversion where possible
+    - performance can drop by a few percent on metadata heavy
+      workloads, the folio sizes are not constant and the calculations
+      add up in the item helpers
+    - both regular and subpage modes
+    - data cannot be converted yet, we need to port that to iomap and
+      there are some other generic changes required
 
 -  convert mount to the new API, should not be user visible:
-   - options deprecated long time ago have been removed: inode_cache,
-     recovery
-   - the new logic that splits mount to two phases slightly changes
-     timing of device scanning for multi-device filesystems
-   - LSM options will now work (like for selinux)
+    - options deprecated long time ago have been removed: inode_cache,
+      recovery
+    - the new logic that splits mount to two phases slightly changes
+      timing of device scanning for multi-device filesystems
+    - LSM options will now work (like for selinux)
 
 - convert delayed nodes radix tree to xarray, preserving the
   preload-like logic that still allows to allocate with GFP_NOFS
@@ -576,9 +576,9 @@ Performance improvements:
   delayed allocation bits, applies to several common workload types
 
 - features under CONFIG_BTRFS_DEBUG:
-  - sysfs knob for setting the how checksums are calculated when submitting IO,
-    inline or offloaded to a thread, this affects latency and throughput on some
-    block group profiles
+   - sysfs knob for setting the how checksums are calculated when submitting IO,
+     inline or offloaded to a thread, this affects latency and throughput on some
+     block group profiles
 
 Notable fixes:
 
@@ -644,29 +644,29 @@ Pull requests:
 User visible features:
 
 - dynamic block group reclaim:
-  - tunable framework to avoid situations where eager data allocations prevent
-    creating new metadata chunks due to lack of unallocated space
-  - reuse sysfs knob bg_reclaim_threshold (otherwise used only in zoned mode)
-    for a fixed value threshold
-  - new on/off sysfs knob "dynamic_reclaim" calculating the value based on
-    heuristics, aiming to keep spare working space for relocating chunks but
-    not to needlessly relocate partially utilized block groups or reclaim newly
-    allocated ones
-  - stats are exported in sysfs per block group type, files "reclaim_*"
-  - this may increase IO load at unexpected times but the corner case of no
-    allocatable block groups is known to be worse
+   - tunable framework to avoid situations where eager data allocations prevent
+     creating new metadata chunks due to lack of unallocated space
+   - reuse sysfs knob bg_reclaim_threshold (otherwise used only in zoned mode)
+     for a fixed value threshold
+   - new on/off sysfs knob "dynamic_reclaim" calculating the value based on
+     heuristics, aiming to keep spare working space for relocating chunks but
+     not to needlessly relocate partially utilized block groups or reclaim newly
+     allocated ones
+   - stats are exported in sysfs per block group type, files "reclaim_*"
+   - this may increase IO load at unexpected times but the corner case of no
+     allocatable block groups is known to be worse
 
 - automatically remove qgroup of deleted subvolumes:
-  - adjust qgroup removal conditions, make sure all related subvolume data are
-    already removed, or return EBUSY, also take into account setting of sysfs
-    drop_subtree_threshold
-  - also works in squota mode
+   - adjust qgroup removal conditions, make sure all related subvolume data are
+     already removed, or return EBUSY, also take into account setting of sysfs
+     drop_subtree_threshold
+   - also works in squota mode
 
 -  mount option updates: new modes of 'rescue=' that allow to mount images
-   (read-only) that could have been partially converted by user space tools
-  - ignoremetacsums  - invalid metadata checksums are ignored
-  - ignoresuperflags - super block flags that track conversion in progress
-                       (like UUID or checksums)
+    (read-only) that could have been partially converted by user space tools
+     - ignoremetacsums  - invalid metadata checksums are ignored
+     - ignoresuperflags - super block flags that track conversion in progress
+                          (like UUID or checksums)
 
 Other notable changes or fixes:
 
-- 
2.47.0

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

[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".

Signed-off-by: Anand Jain <anand.jain@oracle.com>
---
 Documentation/dev/On-disk-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/dev/On-disk-format.rst b/Documentation/dev/On-disk-format.rst
index b3304032651b..39fdaf09b98b 100644
--- a/Documentation/dev/On-disk-format.rst
+++ b/Documentation/dev/On-disk-format.rst
@@ -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".
-- 
2.47.0

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

[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.

Signed-off-by: Anand Jain <anand.jain@oracle.com>
---
 Documentation/Kernel-by-version.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/Documentation/Kernel-by-version.rst b/Documentation/Kernel-by-version.rst
index d1adc3ee6ebf..1066a8a22afd 100644
--- a/Documentation/Kernel-by-version.rst
+++ b/Documentation/Kernel-by-version.rst
@@ -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>`__,
-- 
2.47.0

Re: [PATCH 0/3] btrfs-progs: fix documentation build errors

[David Sterba]

On Tue, Nov 19, 2024 at 02:56:14PM +0800, Anand Jain wrote:
> 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.