Skip to contentSkip to conversation

btrfs-progs: Documentation: fix compile an error and

PATCH Superseded Anand Jain 2 participants 10 messages Jan 8, 2024 – Jan 10, 2024

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Anand Jain

author
#0 lore raw

cover btrfs-progs: Documentation: fix compile an error and

Fixes a warning and an error during the build with Sphinx.

Anand Jain (2):
btrfs-progs: Documentation: fix sphinx code-block warning btrfs-progs Documentation: placeholder for contents.rst file

 Documentation/Tree-checker.rst               |  4 ++--
 Documentation/ch-subvolume-intro.rst         | 10 +++++-----
 Documentation/ch-volume-management-intro.rst |  2 +-
 Documentation/contents.rst                   |  0
 Documentation/dev/Developer-s-FAQ.rst        |  2 +-
 Documentation/dev/Experimental.rst           |  4 ++--
 Documentation/dev/dev-btrfs-design.rst       |  8 ++++----
 Documentation/trouble-index.rst              | 16 ++++++++--------
 8 files changed, 23 insertions(+), 23 deletions(-)
 create mode 100644 Documentation/contents.rst
Signature · 1 line
2.31.1
author
#1 lore raw

PATCH 1/2 btrfs-progs: Documentation: fix sphinx code-block warning

There are several warnings regarding the absence of an argument for the code-block directive on some build servers using python3-sphinx 0.2.2-17.

For example:
Making all in Documentation
[SPHINX] man
ch-subvolume-intro.rst:141: WARNING: Error in "code-block" directive:
1 argument(s) required, 0 supplied.

.. code-block::

27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache

Etc...

Adding the relevant argument.

---
 Documentation/Tree-checker.rst               |  4 ++--
 Documentation/ch-subvolume-intro.rst         | 10 +++++-----
 Documentation/ch-volume-management-intro.rst |  2 +-
 Documentation/dev/Developer-s-FAQ.rst        |  2 +-
 Documentation/dev/Experimental.rst           |  4 ++--
 Documentation/dev/dev-btrfs-design.rst       |  8 ++++----
 Documentation/trouble-index.rst              | 16 ++++++++--------
 7 files changed, 23 insertions(+), 23 deletions(-)
Documentation/Tree-checker.rst +2 -2
index 68df6fdfa0de..c0e5e316d958 100644
@@ -30,7 +30,7 @@ fine.
 
 A message may look like:
 
-.. code-block::
+.. code-block:: text
 
    [ 1716.823895] BTRFS critical (device vdb): corrupt leaf: root=18446744073709551607 block=38092800 slot=0, invalid key objectid: has 1 expect 6 or [256, 18446744073709551360] or 18446744073709551604
    [ 1716.829499] BTRFS info (device vdb): leaf 38092800 gen 19 total ptrs 4 free space 15851 owner 18446744073709551607
@@ -54,7 +54,7 @@ checksum is found to be valid. This protects against changes to the metadata
 that could possibly also update the checksum, less likely to happen accidentally
 but rather due to intentional corruption or fuzzing.
 
-.. code-block::
+.. code-block:: text
 
    [ 4823.612832] BTRFS critical (device vdb): corrupt leaf: root=7 block=30474240 slot=0, invalid nritems, have 0 should not be 0 for non-root leaf
    [ 4823.616798] BTRFS error (device vdb): block=30474240 read time tree block corruption detected
Documentation/ch-subvolume-intro.rst +5 -5
index 57b42fe7a97f..3a138f221cc6 100644
@@ -3,7 +3,7 @@ file/directory hierarchy and inode number namespace. Subvolumes can share file
 extents. A snapshot is also subvolume, but with a given initial content of the
 original subvolume. A subvolume has always inode number 256.
 
-.. note::
+.. note:: text
    A subvolume in BTRFS is not like an LVM logical volume, which is block-level
    snapshot while BTRFS subvolumes are file extent-based.
 
@@ -34,7 +34,7 @@ Subvolumes can be given capacity limits, through the qgroups/quota facility, but
 otherwise share the single storage pool of the whole btrfs filesystem. They may
 even share data between themselves (through deduplication or snapshotting).
 
-.. note::
+.. note:: text
     A snapshot is not a backup: snapshots work by use of BTRFS' copy-on-write
     behaviour. A snapshot and the original it was taken from initially share all
     of the same data blocks. If that data is damaged in some way (cosmic rays,
@@ -68,7 +68,7 @@ change and could potentially break the incremental send use case, performing
 it by :ref:`btrfs property set<man-property-set>` requires force if that is
 really desired by user.
 
-.. note::
+.. note:: text
    The safety checks have been implemented in 5.14.2, any subvolumes previously
    received (with a valid *received_uuid*) and read-write status may exist and
    could still lead to problems with send/receive. You can use :ref:`btrfs subvolume show<man-subvolume-show>`
@@ -138,7 +138,7 @@ Mounting a read-write snapshot as read-only is possible and will not change the
 The name of the mounted subvolume is stored in file :file:`/proc/self/mountinfo` in
 the 4th column:
 
-.. code-block::
+.. code-block:: text
 
    27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache
               ^^^^^^
@@ -151,7 +151,7 @@ then a snapshot is taken, then the cloned directory entry representing the
 subvolume becomes empty and the inode has number 2. All other files and
 directories in the target snapshot preserve their original inode numbers.
 
-.. note::
+.. note:: text
    Inode number is not a filesystem-wide unique identifier, some applications
    assume that. Please use pair *subvolumeid:inodenumber* for that purpose.
    The subvolume id can be read by :ref:`btrfs inspect-internal rootid<man-inspect-rootid>`
Documentation/ch-volume-management-intro.rst +1 -1
index c93576c72586..15b44c9447b8 100644
@@ -27,7 +27,7 @@ RAID level
         standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
         RAID10, RAID5 and RAID6.
 
-.. _man-device-typical-use-cases:
+.. _man-device-typical-use-cases: none
 
 Typical use cases
 -----------------
Documentation/dev/Developer-s-FAQ.rst +1 -1
index 6d8d78e54b4d..f79d96a98cf1 100644
@@ -178,7 +178,7 @@ For the next iteration, add a short description of the changes made, under the
 first **---** (triple dash) marker in the patch. For example (see also Example
 3):
 
-.. code-block::
+.. code-block:: text
 
    ---
    V3: renamed variable
Documentation/dev/Experimental.rst +2 -2
index 4817faa56c79..8dedf667050c 100644
@@ -11,7 +11,7 @@ filed as issues.
 
 In the code use it like:
 
-.. code-block::
+.. code-block:: c
 
     if (EXPERIMENTAL) {
         ...
@@ -22,7 +22,7 @@ where it would break default build.
 
 Or:
 
-.. code-block::
+.. code-block:: c
 
     #if EXPERIMENTAL
     ...
Documentation/dev/dev-btrfs-design.rst +4 -4
index c3a6d73872e9..7ce0b4df6d45 100644
@@ -15,7 +15,7 @@ The Btrfs btree provides a generic facility to store a variety of data
 types. Internally it only knows about three data structures: keys,
 items, and a block header:
 
-.. code-block::
+.. code-block:: c
 
    struct btrfs_header {
            u8 csum[32];
@@ -30,7 +30,7 @@ items, and a block header:
            u8 level;
    }
 
-.. code-block::
+.. code-block:: c
 
    struct btrfs_disk_key {
           __le64 objectid;
@@ -38,7 +38,7 @@ items, and a block header:
           __le64 offset;
    }
 
-.. code-block::
+.. code-block:: c
 
    struct btrfs_item {
           struct btrfs_disk_key key;
@@ -311,7 +311,7 @@ field of the root block may be different from the objectid of the
 snapshot. So, when dropping references on tree roots, the objectid of
 the root structure is always used. When a backref is deleted:
 
-.. code-block::
+.. code-block:: c
 
    if backref was for a tree root:
         root_objectid = root->root_key.objectid
Documentation/trouble-index.rst +8 -8
index 8de7d6232a11..66c75831cd1e 100644
@@ -12,7 +12,7 @@ Error: parent transid verify error
 Reason: result of a failed internal consistency check of the filesystem's metadata.
 Type: permanent
 
-.. code-block::
+.. code-block:: none
 
    [ 4007.489730] BTRFS error (device vdb): parent transid verify failed on 30736384 wanted 10 found 8
 
@@ -59,7 +59,7 @@ persisted and possibly making old copies available.
 The most obvious way how to exhaust space is to create a file until the data
 chunks are full:
 
-.. code-block::
+.. code-block:: bash
 
    $ df -h .
    Filesystem      Size  Used Avail Use% Mounted on
@@ -98,7 +98,7 @@ action is possible. If not, ENOSPC is returned.
 Error: unable to start balance with target metadata profile
 -----------------------------------------------------------
 
-.. code-block::
+.. code-block:: none
 
    unable to start balance with target metadata profile 32
 
@@ -111,7 +111,7 @@ Error: balance will reduce metadata integrity
 
 The full message in system log
 
-.. code-block::
+.. code-block:: none
 
    balance will reduce metadata integrity, use force if you want this
 
@@ -126,7 +126,7 @@ The preferred way is to use the :command:`wipefs` utility that is part of the
 *util-linux* package. Running the command with the device will not destroy
 the data, just list the detected filesystems:
 
-.. code-block::
+.. code-block:: bash
 
    # wipefs /dev/sda
    offset               type
@@ -137,7 +137,7 @@ the data, just list the detected filesystems:
 Remove the filesystem signature at a given offset or wipe all recognized
 signatures on the device:
 
-.. code-block::
+.. code-block:: bash
 
    # wipefs -o 0x10040 /dev/sda
    8 bytes [5f 42 48 52 66 53 5f 4d] erased at offset 0x10040 (btrfs)
@@ -172,7 +172,7 @@ at 64MiB, the third one at 256GiB. The following lines reset the signature
 on all the three copies:
 
 
-.. code-block::
+.. code-block:: bash
 
    # dd if=/dev/zero bs=1 count=8 of=/dev/sda seek=$((64*1024+64))
    # dd if=/dev/zero bs=1 count=8 of=/dev/sda seek=$((64*1024*1024+64))
@@ -180,7 +180,7 @@ on all the three copies:
 
 If you want to restore the super block signatures:
 
-.. code-block::
+.. code-block:: bash
 
    # echo "_BHRfS_M" | dd bs=1 count=8 of=/dev/sda seek=$((64*1024+64))
    # echo "_BHRfS_M" | dd bs=1 count=8 of=/dev/sda seek=$((64*1024*1024+64))
Signature · 1 line
2.31.1
author
#4 lore raw

RFC PATCH 2/2 btrfs-progs Documentation: placeholder for contents.rst file

In reply to Anand Jain

For now, to circumvent the build error, create a placeholder file named contents.rst.

Sphinx error:
master file btrfs-progs/Documentation/contents.rst not found make[1]: *** [Makefile:37: man] Error 2
make: *** [Makefile:502: build-Documentation] Error 2

---
RFC because the empty contents.rst to fix the error.

 Documentation/contents.rst | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/contents.rst
Documentation/contents.rst new file +0 -0
new file mode 100644
index 000000000000..e69de29bb2d1
Signature · 1 line
2.31.1
#5 lore raw

Re: [PATCH RFC 2/2] btrfs-progs Documentation: placeholder for contents.rst file

Quoted 5 lines · Anand Jain

For now, to circumvent the build error, create a placeholder file named contents.rst.

Sphinx error:
master file btrfs-progs/Documentation/contents.rst not found

I don't see that error with sphinx 7.2.6, which version do you use?

Quoted 6 lines

make[1]: *** [Makefile:37: man] Error 2
make: *** [Makefile:502: build-Documentation] Error 2

---
RFC because the empty contents.rst to fix the error.

Adding an empty file to silence the error is probably ok but what's the reason to have it?

author
#6 lore raw

Re: [PATCH RFC 2/2] btrfs-progs Documentation: placeholder for contents.rst file

Quoted 9 lines · David Sterba
Quoted 5 lines · Anand Jain

For now, to circumvent the build error, create a placeholder file named contents.rst.

Sphinx error:
master file btrfs-progs/Documentation/contents.rst not found

I don't see that error with sphinx 7.2.6, which version do you use?

python3-sphinx-3.4.3-7.el9.noarch -- no issues python3-sphinx-1.7.6-3.el8.noarch -- build errors as above.

Quoted 9 lines
Quoted 6 lines

make[1]: *** [Makefile:37: man] Error 2
make: *** [Makefile:502: build-Documentation] Error 2

---
RFC because the empty contents.rst to fix the error.

Adding an empty file to silence the error is probably ok but what's the reason to have it?

While contents.rst similar to index.rst with its Table of Contents (TOC) and toctree directives. But, I am not sure yet if we can replace index.rst with contents.rst. And doing it ended up with multiple errors. So, I abandoned the idea, restored to creating an empty file instead. It appears that contents.rst is needed only in older versions like' 1.7.6.

Thanks, Anand

#2 lore raw

Re: [PATCH 1/2] btrfs-progs: Documentation: fix sphinx code-block warning

In reply to Anand Jain

Documentation/Tree-checker.rst fine. · line 33

Quoted 10 lines · Anand Jain
Documentation/Tree-checker.rst +1 -1
index 68df6fdfa0de..c0e5e316d958 100644
@@ -30,7 +30,7 @@ fine.
 
 A message may look like:
 
-.. code-block::
+.. code-block:: text

No syntax hilighting is specified as 'none' elsewhere, so I'd change that to be consistent.

Quoted 17 lines
Documentation/Tree-checker.rst +1 -1
    [ 1716.823895] BTRFS critical (device vdb): corrupt leaf: root=18446744073709551607 block=38092800 slot=0, invalid key objectid: has 1 expect 6 or [256, 18446744073709551360] or 18446744073709551604
    [ 1716.829499] BTRFS info (device vdb): leaf 38092800 gen 19 total ptrs 4 free space 15851 owner 18446744073709551607
@@ -54,7 +54,7 @@ checksum is found to be valid. This protects against changes to the metadata
 that could possibly also update the checksum, less likely to happen accidentally
 but rather due to intentional corruption or fuzzing.
 
-.. code-block::
+.. code-block:: text
 
    [ 4823.612832] BTRFS critical (device vdb): corrupt leaf: root=7 block=30474240 slot=0, invalid nritems, have 0 should not be 0 for non-root leaf
    [ 4823.616798] BTRFS error (device vdb): block=30474240 read time tree block corruption detected
Documentation/ch-subvolume-intro.rst +0 -0
index 57b42fe7a97f..3a138f221cc6 100644

Documentation/ch-subvolume-intro.rst file/directory hierarchy and inode number namespace. Subvolumes can share file · line 6

Quoted 5 lines
Documentation/ch-subvolume-intro.rst +1 -1
@@ -3,7 +3,7 @@ file/directory hierarchy and inode number namespace. Subvolumes can share file
 extents. A snapshot is also subvolume, but with a given initial content of the
 original subvolume. A subvolume has always inode number 256.
 
-.. note::
+.. note:: text

Does note really need the paramter? You've added 4 but there are 70+ in the whole documentation so that would need fixing them all (or none).

Quoted 44 lines
Documentation/ch-subvolume-intro.rst +4 -4
    A subvolume in BTRFS is not like an LVM logical volume, which is block-level
    snapshot while BTRFS subvolumes are file extent-based.
 
@@ -34,7 +34,7 @@ Subvolumes can be given capacity limits, through the qgroups/quota facility, but
 otherwise share the single storage pool of the whole btrfs filesystem. They may
 even share data between themselves (through deduplication or snapshotting).
 
-.. note::
+.. note:: text
     A snapshot is not a backup: snapshots work by use of BTRFS' copy-on-write
     behaviour. A snapshot and the original it was taken from initially share all
     of the same data blocks. If that data is damaged in some way (cosmic rays,
@@ -68,7 +68,7 @@ change and could potentially break the incremental send use case, performing
 it by :ref:`btrfs property set<man-property-set>` requires force if that is
 really desired by user.
 
-.. note::
+.. note:: text
    The safety checks have been implemented in 5.14.2, any subvolumes previously
    received (with a valid *received_uuid*) and read-write status may exist and
    could still lead to problems with send/receive. You can use :ref:`btrfs subvolume show<man-subvolume-show>`
@@ -138,7 +138,7 @@ Mounting a read-write snapshot as read-only is possible and will not change the
 The name of the mounted subvolume is stored in file :file:`/proc/self/mountinfo` in
 the 4th column:
 
-.. code-block::
+.. code-block:: text
 
    27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache
               ^^^^^^
@@ -151,7 +151,7 @@ then a snapshot is taken, then the cloned directory entry representing the
 subvolume becomes empty and the inode has number 2. All other files and
 directories in the target snapshot preserve their original inode numbers.
 
-.. note::
+.. note:: text
    Inode number is not a filesystem-wide unique identifier, some applications
    assume that. Please use pair *subvolumeid:inodenumber* for that purpose.
    The subvolume id can be read by :ref:`btrfs inspect-internal rootid<man-inspect-rootid>`
Documentation/ch-volume-management-intro.rst +0 -0
index c93576c72586..15b44c9447b8 100644

Documentation/ch-volume-management-intro.rst RAID level · line 30

Quoted 5 lines
Documentation/ch-volume-management-intro.rst +1 -1
@@ -27,7 +27,7 @@ RAID level
         standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
         RAID10, RAID5 and RAID6.
 
-.. _man-device-typical-use-cases:
+.. _man-device-typical-use-cases: none

This is a label for a reference, I doubt it needs a parameter.

The rest looks ok, thanks.

#7 lore raw

Re: [PATCH RFC 2/2] btrfs-progs Documentation: placeholder for contents.rst file

In reply to Anand Jain
Quoted 28 lines · Anand Jain
Quoted 9 lines · David Sterba
Quoted 5 lines · Anand Jain

For now, to circumvent the build error, create a placeholder file named contents.rst.

Sphinx error:
master file btrfs-progs/Documentation/contents.rst not found

I don't see that error with sphinx 7.2.6, which version do you use?

   python3-sphinx-3.4.3-7.el9.noarch  -- no issues
   python3-sphinx-1.7.6-3.el8.noarch  -- build errors as above.
Quoted 9 lines
Quoted 6 lines

make[1]: *** [Makefile:37: man] Error 2
make: *** [Makefile:502: build-Documentation] Error 2

---
RFC because the empty contents.rst to fix the error.

Adding an empty file to silence the error is probably ok but what's the reason to have it?

Quoted 6 lines

While contents.rst similar to index.rst with its Table of Contents (TOC) and toctree directives. But, I am not sure yet if we can replace index.rst with contents.rst. And doing it ended up with multiple errors. So, I abandoned the idea, restored to creating an empty file instead. It appears that contents.rst is needed only in older versions like' 1.7.6.

Ok then, the empty file would be a fix but it leads to this warning on a newer version:

.../contents.rst: WARNING: document isn't included in any toctree

We could add it conditionally at build time in case the sphinx version is old, with something like that:

.PHONY: contents.rst

contents.rst:

	if "sphinx --version < 3.2.1"; then touch contents.rst; fi
author
#3 lore raw

Re: [PATCH 1/2] btrfs-progs: Documentation: fix sphinx code-block warning

In reply to David Sterba
Quoted 7 lines · David Sterba
Quoted 6 lines · Anand Jain
Documentation/Tree-checker.rst +0 -0
index 68df6fdfa0de..c0e5e316d958 100644
@@ -30,7 +30,7 @@ fine.
 
Quoted 8 lines

Documentation/Tree-checker.rst fine. · line 33

Quoted 4 lines
Documentation/Tree-checker.rst +1 -1
  A message may look like:
 
-.. code-block::
+.. code-block:: text

No syntax hilighting is specified as 'none' elsewhere, so I'd change that to be consistent.

Yeah. I'll update.

Quoted 20 lines
Quoted 20 lines
Documentation/Tree-checker.rst +1 -1
     [ 1716.823895] BTRFS critical (device vdb): corrupt leaf: root=18446744073709551607 block=38092800 slot=0, invalid key objectid: has 1 expect 6 or [256, 18446744073709551360] or 18446744073709551604
     [ 1716.829499] BTRFS info (device vdb): leaf 38092800 gen 19 total ptrs 4 free space 15851 owner 18446744073709551607
@@ -54,7 +54,7 @@ checksum is found to be valid. This protects against changes to the metadata
  that could possibly also update the checksum, less likely to happen accidentally
  but rather due to intentional corruption or fuzzing.
 
-.. code-block::
+.. code-block:: text
 
     [ 4823.612832] BTRFS critical (device vdb): corrupt leaf: root=7 block=30474240 slot=0, invalid nritems, have 0 should not be 0 for non-root leaf
     [ 4823.616798] BTRFS error (device vdb): block=30474240 read time tree block corruption detected
Documentation/ch-subvolume-intro.rst +0 -0
index 57b42fe7a97f..3a138f221cc6 100644
@@ -3,7 +3,7 @@ file/directory hierarchy and inode number namespace. Subvolumes can share file
  extents. A snapshot is also subvolume, but with a given initial content of the
  original subvolume. A subvolume has always inode number 256.
 
Quoted 6 lines

Documentation/ch-subvolume-intro.rst file/directory hierarchy and inode number namespace. Subvolumes can share file · line 6

Quoted 2 lines
Documentation/ch-subvolume-intro.rst +1 -1
-.. note::
+.. note:: text

Does note really need the paramter? You've added 4 but there are 70+ in the whole documentation so that would need fixing them all (or none).

My bad these shouldn't be here. I am fixing it. Thx.

Quoted 47 lines
Quoted 47 lines
Documentation/ch-subvolume-intro.rst +4 -4
     A subvolume in BTRFS is not like an LVM logical volume, which is block-level
     snapshot while BTRFS subvolumes are file extent-based.
 
@@ -34,7 +34,7 @@ Subvolumes can be given capacity limits, through the qgroups/quota facility, but
  otherwise share the single storage pool of the whole btrfs filesystem. They may
  even share data between themselves (through deduplication or snapshotting).
 
-.. note::
+.. note:: text
      A snapshot is not a backup: snapshots work by use of BTRFS' copy-on-write
      behaviour. A snapshot and the original it was taken from initially share all
      of the same data blocks. If that data is damaged in some way (cosmic rays,
@@ -68,7 +68,7 @@ change and could potentially break the incremental send use case, performing
  it by :ref:`btrfs property set<man-property-set>` requires force if that is
  really desired by user.
 
-.. note::
+.. note:: text
     The safety checks have been implemented in 5.14.2, any subvolumes previously
     received (with a valid *received_uuid*) and read-write status may exist and
     could still lead to problems with send/receive. You can use :ref:`btrfs subvolume show<man-subvolume-show>`
@@ -138,7 +138,7 @@ Mounting a read-write snapshot as read-only is possible and will not change the
  The name of the mounted subvolume is stored in file :file:`/proc/self/mountinfo` in
  the 4th column:
 
-.. code-block::
+.. code-block:: text
 
     27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache
                ^^^^^^
@@ -151,7 +151,7 @@ then a snapshot is taken, then the cloned directory entry representing the
  subvolume becomes empty and the inode has number 2. All other files and
  directories in the target snapshot preserve their original inode numbers.
 
-.. note::
+.. note:: text
     Inode number is not a filesystem-wide unique identifier, some applications
     assume that. Please use pair *subvolumeid:inodenumber* for that purpose.
     The subvolume id can be read by :ref:`btrfs inspect-internal rootid<man-inspect-rootid>`
Documentation/ch-volume-management-intro.rst +0 -0
index c93576c72586..15b44c9447b8 100644
@@ -27,7 +27,7 @@ RAID level
          standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
          RAID10, RAID5 and RAID6.
 
Quoted 4 lines

Documentation/ch-volume-management-intro.rst RAID level · line 30

Quoted 2 lines
Documentation/ch-volume-management-intro.rst +1 -1
-.. _man-device-typical-use-cases:
+.. _man-device-typical-use-cases: none

This is a label for a reference, I doubt it needs a parameter.

My intention is to fix only the code-block.
I'll make sure it is, in v2.

Quoted 1 line

The rest looks ok, thanks.

Thanks !
Anand

author
#8 lore raw

Re: [PATCH RFC 2/2] btrfs-progs Documentation: placeholder for contents.rst file

In reply to David Sterba
Quoted 41 lines · David Sterba
Quoted 28 lines · Anand Jain
Quoted 9 lines · David Sterba
Quoted 5 lines · Anand Jain

For now, to circumvent the build error, create a placeholder file named contents.rst.

Sphinx error:
master file btrfs-progs/Documentation/contents.rst not found

I don't see that error with sphinx 7.2.6, which version do you use?

    python3-sphinx-3.4.3-7.el9.noarch  -- no issues
    python3-sphinx-1.7.6-3.el8.noarch  -- build errors as above.
Quoted 9 lines
Quoted 6 lines

make[1]: *** [Makefile:37: man] Error 2
make: *** [Makefile:502: build-Documentation] Error 2

---
RFC because the empty contents.rst to fix the error.

Adding an empty file to silence the error is probably ok but what's the reason to have it?

Quoted 6 lines

While contents.rst similar to index.rst with its Table of Contents (TOC) and toctree directives. But, I am not sure yet if we can replace index.rst with contents.rst. And doing it ended up with multiple errors. So, I abandoned the idea, restored to creating an empty file instead. It appears that contents.rst is needed only in older versions like' 1.7.6.

Ok then, the empty file would be a fix but it leads to this warning on a newer version:

.../contents.rst: WARNING: document isn't included in any toctree

Quoted 7 lines

We could add it conditionally at build time in case the sphinx version is old, with something like that:

.PHONY: contents.rst

contents.rst:

	if "sphinx --version < 3.2.1"; then touch contents.rst; fi

Ah. Thanks let me try.

Also, I am testing it manually using man, is there anything I am missing?

Thanks,
-Anand

#9 lore raw

Re: [PATCH RFC 2/2] btrfs-progs Documentation: placeholder for contents.rst file

Quoted 21 lines · Anand Jain
Quoted 21 lines
Quoted 6 lines
Quoted 5 lines
Quoted 2 lines

---
RFC because the empty contents.rst to fix the error.

Adding an empty file to silence the error is probably ok but what's the reason to have it?

Quoted 6 lines

While contents.rst similar to index.rst with its Table of Contents (TOC) and toctree directives. But, I am not sure yet if we can replace index.rst with contents.rst. And doing it ended up with multiple errors. So, I abandoned the idea, restored to creating an empty file instead. It appears that contents.rst is needed only in older versions like' 1.7.6.

Ok then, the empty file would be a fix but it leads to this warning on a newer version:

.../contents.rst: WARNING: document isn't included in any toctree

We could add it conditionally at build time in case the sphinx version is old, with something like that:

Quoted 8 lines
Quoted 4 lines

.PHONY: contents.rst

contents.rst:

	if "sphinx --version < 3.2.1"; then touch contents.rst; fi

Ah. Thanks let me try.

Also, I am testing it manually using man, is there anything I am missing?

I think not, the manual pages are default build target, although you can also try 'make html' if it's without warnings.