| Message ID | b30031c129e92c7e99c7e5bc818a456cd5828cc8.1704438755.git.anand.jain@oracle.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | btrfs-progs: Documentation: fix compile an error and | expand |
On Mon, Jan 08, 2024 at 04:31:08PM +0800, Anand Jain wrote: > 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? > make[1]: *** [Makefile:37: man] Error 2 > make: *** [Makefile:502: build-Documentation] Error 2 > > Signed-off-by: Anand Jain <anand.jain@oracle.com> > --- > 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?
On 09/01/2024 05:33, David Sterba wrote: > On Mon, Jan 08, 2024 at 04:31:08PM +0800, Anand Jain wrote: >> 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. >> make[1]: *** [Makefile:37: man] Error 2 >> make: *** [Makefile:502: build-Documentation] Error 2 >> >> Signed-off-by: Anand Jain <anand.jain@oracle.com> >> --- >> 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
On Tue, Jan 09, 2024 at 09:25:37PM +0800, Anand Jain wrote: > > > > On 09/01/2024 05:33, David Sterba wrote: > > On Mon, Jan 08, 2024 at 04:31:08PM +0800, Anand Jain wrote: > >> 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. > > > >> make[1]: *** [Makefile:37: man] Error 2 > >> make: *** [Makefile:502: build-Documentation] Error 2 > >> > >> Signed-off-by: Anand Jain <anand.jain@oracle.com> > >> --- > >> 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. 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
On 09/01/2024 21:53, David Sterba wrote: > On Tue, Jan 09, 2024 at 09:25:37PM +0800, Anand Jain wrote: >> >> >> >> On 09/01/2024 05:33, David Sterba wrote: >>> On Mon, Jan 08, 2024 at 04:31:08PM +0800, Anand Jain wrote: >>>> 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. >> >> >>>> make[1]: *** [Makefile:37: man] Error 2 >>>> make: *** [Makefile:502: build-Documentation] Error 2 >>>> >>>> Signed-off-by: Anand Jain <anand.jain@oracle.com> >>>> --- >>>> 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. > > 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 Ah. Thanks let me try. Also, I am testing it manually using man, is there anything I am missing? Thanks, -Anand
On Wed, Jan 10, 2024 at 06:06:11AM +0530, Anand Jain wrote: > >>>> --- > >>>> 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. > > > > 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 > > 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.
diff --git a/Documentation/contents.rst b/Documentation/contents.rst new file mode 100644 index 000000000000..e69de29bb2d1
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 Signed-off-by: Anand Jain <anand.jain@oracle.com> --- 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