* [PATCH v2 0/2] btrfs-progs: Documentation: fix compile an error and
@ 2024-01-10 17:25 Anand Jain
2024-01-10 17:25 ` [PATCH v2 1/2] btrfs-progs: Documentation: fix sphinx code-block warning Anand Jain
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Anand Jain @ 2024-01-10 17:25 UTC (permalink / raw)
To: linux-btrfs; +Cc: dsterba
v2:
Fix only the code-block:: without the argument and set it to none to
match the rest of the code blocks.
Use Documentation/Makefile.in to create the contents.rst file.
Link to v1: https://lore.kernel.org/all/cover.1704438755.git.anand.jain@oracle.com/
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
.gitignore | 1 +
Documentation/Makefile.in | 8 ++++++++
Documentation/Tree-checker.rst | 4 ++--
Documentation/ch-subvolume-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 ++++++++--------
Makefile | 7 +++++++
9 files changed, 34 insertions(+), 18 deletions(-)
--
2.31.1
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v2 1/2] btrfs-progs: Documentation: fix sphinx code-block warning 2024-01-10 17:25 [PATCH v2 0/2] btrfs-progs: Documentation: fix compile an error and Anand Jain @ 2024-01-10 17:25 ` Anand Jain 2024-01-10 17:25 ` [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file Anand Jain 2024-01-11 4:21 ` [PATCH] btrfs-progs: fixup: v2 " Anand Jain 2 siblings, 0 replies; 7+ messages in thread From: Anand Jain @ 2024-01-10 17:25 UTC (permalink / raw) To: linux-btrfs; +Cc: dsterba 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 none argument. Signed-off-by: Anand Jain <anand.jain@oracle.com> --- Documentation/Tree-checker.rst | 4 ++-- Documentation/ch-subvolume-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 ++++++++-------- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/Documentation/Tree-checker.rst b/Documentation/Tree-checker.rst index 68df6fdfa0de..620c203f098e 100644 --- a/Documentation/Tree-checker.rst +++ b/Documentation/Tree-checker.rst @@ -30,7 +30,7 @@ fine. A message may look like: -.. code-block:: +.. code-block:: none [ 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:: none [ 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 diff --git a/Documentation/ch-subvolume-intro.rst b/Documentation/ch-subvolume-intro.rst index 57b42fe7a97f..9ca39d0adba2 100644 --- a/Documentation/ch-subvolume-intro.rst +++ b/Documentation/ch-subvolume-intro.rst @@ -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:: none 27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache ^^^^^^ diff --git a/Documentation/dev/Developer-s-FAQ.rst b/Documentation/dev/Developer-s-FAQ.rst index 6d8d78e54b4d..496900415a67 100644 --- a/Documentation/dev/Developer-s-FAQ.rst +++ b/Documentation/dev/Developer-s-FAQ.rst @@ -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:: none --- V3: renamed variable diff --git a/Documentation/dev/Experimental.rst b/Documentation/dev/Experimental.rst index 4817faa56c79..70d14850f5c8 100644 --- a/Documentation/dev/Experimental.rst +++ b/Documentation/dev/Experimental.rst @@ -11,7 +11,7 @@ filed as issues. In the code use it like: -.. code-block:: +.. code-block:: none if (EXPERIMENTAL) { ... @@ -22,7 +22,7 @@ where it would break default build. Or: -.. code-block:: +.. code-block:: none #if EXPERIMENTAL ... diff --git a/Documentation/dev/dev-btrfs-design.rst b/Documentation/dev/dev-btrfs-design.rst index c3a6d73872e9..befd30a114ba 100644 --- a/Documentation/dev/dev-btrfs-design.rst +++ b/Documentation/dev/dev-btrfs-design.rst @@ -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:: none struct btrfs_header { u8 csum[32]; @@ -30,7 +30,7 @@ items, and a block header: u8 level; } -.. code-block:: +.. code-block:: none struct btrfs_disk_key { __le64 objectid; @@ -38,7 +38,7 @@ items, and a block header: __le64 offset; } -.. code-block:: +.. code-block:: none 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:: none if backref was for a tree root: root_objectid = root->root_key.objectid diff --git a/Documentation/trouble-index.rst b/Documentation/trouble-index.rst index 8de7d6232a11..4d07c85106fb 100644 --- a/Documentation/trouble-index.rst +++ b/Documentation/trouble-index.rst @@ -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:: none $ 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:: none # 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:: none # 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:: none # 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:: none # 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)) -- 2.31.1 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file 2024-01-10 17:25 [PATCH v2 0/2] btrfs-progs: Documentation: fix compile an error and Anand Jain 2024-01-10 17:25 ` [PATCH v2 1/2] btrfs-progs: Documentation: fix sphinx code-block warning Anand Jain @ 2024-01-10 17:25 ` Anand Jain 2024-01-10 21:52 ` David Sterba 2024-01-11 4:21 ` [PATCH] btrfs-progs: fixup: v2 " Anand Jain 2 siblings, 1 reply; 7+ messages in thread From: Anand Jain @ 2024-01-10 17:25 UTC (permalink / raw) To: linux-btrfs; +Cc: dsterba 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 This build error is seen on version 1.7.6-3 of the sphinx-build. For now, to circumvent the build error, create a placeholder file named contents.rst using the Makefile also add its cleanup. Signed-off-by: Anand Jain <anand.jain@oracle.com> --- .gitignore | 1 + Documentation/Makefile.in | 8 ++++++++ Makefile | 7 +++++++ 3 files changed, 16 insertions(+) diff --git a/.gitignore b/.gitignore index 26f1940d5546..bb719b41d200 100644 --- a/.gitignore +++ b/.gitignore @@ -79,5 +79,6 @@ /Documentation/Makefile /Documentation/_build +/Documentation/contents.rst *.patch diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in index ffc253863ba8..2c036eef00fa 100644 --- a/Documentation/Makefile.in +++ b/Documentation/Makefile.in @@ -28,6 +28,12 @@ man5dir = $(mandir)/man5 man8dir = $(mandir)/man8 .PHONY: all man help +.PHONY: contents.rst + +contents.rst: + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ + touch contents.rst; \ + fi # Build manual pages by default @@ -53,6 +59,8 @@ uninstall: clean: $(QUIET_RM)$(RM) -rf $(BUILDDIR)/* $(QUIET_RM)$(RM) -df -- $(BUILDDIR) + $(QUIET_RM)$(RM) -f contents.rst + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/Makefile b/Makefile index 374f59b99150..a031b0726a9c 100644 --- a/Makefile +++ b/Makefile @@ -417,6 +417,12 @@ endif .PHONY: $(CLEANDIRS) .PHONY: all install clean .PHONY: FORCE +.PHONY: contents.rst + +contents.rst: + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ + touch Documentation/contents.rst; \ + fi # Create all the static targets static_objects = $(patsubst %.o, %.static.o, $(objects)) @@ -910,6 +916,7 @@ endif clean-doc: @echo "Cleaning Documentation" $(Q)$(MAKE) $(MAKEOPTS) -C Documentation clean + $(Q)$(RM) -f -- Documentation/contents.rst clean-gen: @echo "Cleaning Generated Files" -- 2.31.1 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file 2024-01-10 17:25 ` [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file Anand Jain @ 2024-01-10 21:52 ` David Sterba 2024-01-11 4:20 ` Anand Jain 0 siblings, 1 reply; 7+ messages in thread From: David Sterba @ 2024-01-10 21:52 UTC (permalink / raw) To: Anand Jain; +Cc: linux-btrfs, dsterba On Wed, Jan 10, 2024 at 10:55:23PM +0530, Anand Jain wrote: > 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 > > This build error is seen on version 1.7.6-3 of the sphinx-build. > > For now, to circumvent the build error, create a placeholder file > named contents.rst using the Makefile also add its cleanup. > > Signed-off-by: Anand Jain <anand.jain@oracle.com> Added to devel, thanks. > --- > .gitignore | 1 + > Documentation/Makefile.in | 8 ++++++++ > Makefile | 7 +++++++ > 3 files changed, 16 insertions(+) > > diff --git a/.gitignore b/.gitignore > index 26f1940d5546..bb719b41d200 100644 > --- a/.gitignore > +++ b/.gitignore > @@ -79,5 +79,6 @@ > > /Documentation/Makefile > /Documentation/_build > +/Documentation/contents.rst > > *.patch > diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in > index ffc253863ba8..2c036eef00fa 100644 > --- a/Documentation/Makefile.in > +++ b/Documentation/Makefile.in > @@ -28,6 +28,12 @@ man5dir = $(mandir)/man5 > man8dir = $(mandir)/man8 > > .PHONY: all man help > +.PHONY: contents.rst > + > +contents.rst: > + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ > + touch contents.rst; \ > + fi > > # Build manual pages by default > > @@ -53,6 +59,8 @@ uninstall: > clean: > $(QUIET_RM)$(RM) -rf $(BUILDDIR)/* > $(QUIET_RM)$(RM) -df -- $(BUILDDIR) > + $(QUIET_RM)$(RM) -f contents.rst > + > > # Catch-all target: route all unknown targets to Sphinx using the new > # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). > diff --git a/Makefile b/Makefile > index 374f59b99150..a031b0726a9c 100644 > --- a/Makefile > +++ b/Makefile > @@ -417,6 +417,12 @@ endif > .PHONY: $(CLEANDIRS) > .PHONY: all install clean > .PHONY: FORCE > +.PHONY: contents.rst > + > +contents.rst: > + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ > + touch Documentation/contents.rst; \ > + fi > > # Create all the static targets > static_objects = $(patsubst %.o, %.static.o, $(objects)) > @@ -910,6 +916,7 @@ endif > clean-doc: > @echo "Cleaning Documentation" > $(Q)$(MAKE) $(MAKEOPTS) -C Documentation clean > + $(Q)$(RM) -f -- Documentation/contents.rst You don't need to remove the file again, it's in the clean: target in the documentation directory. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file 2024-01-10 21:52 ` David Sterba @ 2024-01-11 4:20 ` Anand Jain 0 siblings, 0 replies; 7+ messages in thread From: Anand Jain @ 2024-01-11 4:20 UTC (permalink / raw) To: dsterba; +Cc: linux-btrfs, dsterba On 1/11/24 05:52, David Sterba wrote: > On Wed, Jan 10, 2024 at 10:55:23PM +0530, Anand Jain wrote: >> 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 >> >> This build error is seen on version 1.7.6-3 of the sphinx-build. >> >> For now, to circumvent the build error, create a placeholder file >> named contents.rst using the Makefile also add its cleanup. >> >> Signed-off-by: Anand Jain <anand.jain@oracle.com> > > Added to devel, thanks. > >> --- >> .gitignore | 1 + >> Documentation/Makefile.in | 8 ++++++++ >> Makefile | 7 +++++++ >> 3 files changed, 16 insertions(+) >> >> diff --git a/.gitignore b/.gitignore >> index 26f1940d5546..bb719b41d200 100644 >> --- a/.gitignore >> +++ b/.gitignore >> @@ -79,5 +79,6 @@ >> >> /Documentation/Makefile >> /Documentation/_build >> +/Documentation/contents.rst >> >> *.patch >> diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in >> index ffc253863ba8..2c036eef00fa 100644 >> --- a/Documentation/Makefile.in >> +++ b/Documentation/Makefile.in >> @@ -28,6 +28,12 @@ man5dir = $(mandir)/man5 >> man8dir = $(mandir)/man8 >> >> .PHONY: all man help >> +.PHONY: contents.rst >> + >> +contents.rst: >> + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ >> + touch contents.rst; \ >> + fi >> >> # Build manual pages by default >> >> @@ -53,6 +59,8 @@ uninstall: >> clean: >> $(QUIET_RM)$(RM) -rf $(BUILDDIR)/* >> $(QUIET_RM)$(RM) -df -- $(BUILDDIR) >> + $(QUIET_RM)$(RM) -f contents.rst >> + >> >> # Catch-all target: route all unknown targets to Sphinx using the new >> # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). >> diff --git a/Makefile b/Makefile >> index 374f59b99150..a031b0726a9c 100644 >> --- a/Makefile >> +++ b/Makefile >> @@ -417,6 +417,12 @@ endif >> .PHONY: $(CLEANDIRS) >> .PHONY: all install clean >> .PHONY: FORCE >> +.PHONY: contents.rst >> + >> +contents.rst: >> + @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ >> + touch Documentation/contents.rst; \ >> + fi >> And we don't' need this either. I'll send a fixup based on your devel. >> # Create all the static targets >> static_objects = $(patsubst %.o, %.static.o, $(objects)) >> @@ -910,6 +916,7 @@ endif >> clean-doc: >> @echo "Cleaning Documentation" >> $(Q)$(MAKE) $(MAKEOPTS) -C Documentation clean >> + $(Q)$(RM) -f -- Documentation/contents.rst > > You don't need to remove the file again, it's in the clean: target in > the documentation directory. Thanks!, Anand ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH] btrfs-progs: fixup: v2 Documentation: placeholder for contents.rst file 2024-01-10 17:25 [PATCH v2 0/2] btrfs-progs: Documentation: fix compile an error and Anand Jain 2024-01-10 17:25 ` [PATCH v2 1/2] btrfs-progs: Documentation: fix sphinx code-block warning Anand Jain 2024-01-10 17:25 ` [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file Anand Jain @ 2024-01-11 4:21 ` Anand Jain 2024-01-11 16:05 ` David Sterba 2 siblings, 1 reply; 7+ messages in thread From: Anand Jain @ 2024-01-11 4:21 UTC (permalink / raw) To: dsterba; +Cc: linux-btrfs We don't need touch Documentation/contents.rst in the Makefile when Documentation/Makefile.in is doing it. Fix the devel commit 7479e750ba65 ("btrfs-progs: docs: placeholder for contents.rst file on older sphinx version"). Signed-off-by: Anand Jain <anand.jain@oracle.com> --- Makefile | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Makefile b/Makefile index d206928e9c86..374f59b99150 100644 --- a/Makefile +++ b/Makefile @@ -417,12 +417,6 @@ endif .PHONY: $(CLEANDIRS) .PHONY: all install clean .PHONY: FORCE -.PHONY: contents.rst - -contents.rst: - @if [ "$$(sphinx-build --version | cut -d' ' -f2)" \< "1.7.7" ]; then \ - touch Documentation/contents.rst; \ - fi # Create all the static targets static_objects = $(patsubst %.o, %.static.o, $(objects)) -- 2.39.2 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] btrfs-progs: fixup: v2 Documentation: placeholder for contents.rst file 2024-01-11 4:21 ` [PATCH] btrfs-progs: fixup: v2 " Anand Jain @ 2024-01-11 16:05 ` David Sterba 0 siblings, 0 replies; 7+ messages in thread From: David Sterba @ 2024-01-11 16:05 UTC (permalink / raw) To: Anand Jain; +Cc: dsterba, linux-btrfs On Thu, Jan 11, 2024 at 12:21:00PM +0800, Anand Jain wrote: > We don't need touch Documentation/contents.rst in the Makefile when > Documentation/Makefile.in is doing it. Fix the devel commit 7479e750ba65 > ("btrfs-progs: docs: placeholder for contents.rst file on older sphinx version"). Thanks, I was not sure if the file should be in the toplevel directory too. Updated in devel. ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2024-01-11 16:06 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2024-01-10 17:25 [PATCH v2 0/2] btrfs-progs: Documentation: fix compile an error and Anand Jain 2024-01-10 17:25 ` [PATCH v2 1/2] btrfs-progs: Documentation: fix sphinx code-block warning Anand Jain 2024-01-10 17:25 ` [PATCH v2 2/2] btrfs-progs Documentation: placeholder for contents.rst file Anand Jain 2024-01-10 21:52 ` David Sterba 2024-01-11 4:20 ` Anand Jain 2024-01-11 4:21 ` [PATCH] btrfs-progs: fixup: v2 " Anand Jain 2024-01-11 16:05 ` David Sterba
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox