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

[David Sterba <dsterba@suse.cz>]

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.