confusing ReST/html

confusing ReST/html

[Randy Dunlap]

I'm comparing Documentation/core-api/index.{rst,html} and
Documentation/driver-api/index.{rst,html}.

Lots (but not all) .rst files end with something like

.. only:: subproject and html

   Indices
   =======

   * :ref:`genindex`

Both of the core-api & driver-api index.rst files do...
with the difference being that core-api/index.rst has
one space following ".. only::" while driver-api/index.rst
has 2 spaces following ".. only::".

Does that make a difference?

When looking at the end/bottom of core-api/index.html,
there is *NO* heading "Indices" and *NO* link "Index" as there
is in driver-api/index.html.
Why? 

There are other cases like this one:

$ cd Documentation; git grep "^\.\. only:: [^ ]"

RCU/index.rst:.. only:: subproject and html
core-api/index.rst:.. only:: subproject and html
rust/index.rst:.. only:: rustdoc and html
rust/index.rst:.. only:: not rustdoc and html
trace/index.rst:.. only:: subproject and html
virt/index.rst:.. only:: html and subproject
wmi/devices/index.rst:.. only:: subproject and html


thanks.
-- 
~Randy

Re: confusing ReST/html

[Mauro Carvalho Chehab]

Hi Randy,

Em Tue, 11 Nov 2025 20:59:25 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> I'm comparing Documentation/core-api/index.{rst,html} and
> Documentation/driver-api/index.{rst,html}.
> 
> Lots (but not all) .rst files end with something like
> 
> .. only:: subproject and html

This is related to partial documentation builds.

- On PDF, we don't want to have an "Indices" section. With PDF, LaTeX
  will always generate an index, outside the "Indices" section, so it
  ends producing an empty section there.

  That's why the rule has "and html".

- Our building system adds "subproject" when one uses SPHINXDOCS.
  The above logic ensures that a partial build will have its own index.

  If you want, try to add/remove it and see what happens when building 
  with SPHINXDOCS. Btw, the quickest one to test is peci:

	make SPHINXDOCS=peci htmldocs

  If everything is working as expected (I haven't test it for years),
  on index.rst that contains it, you'll see an index. Removing it will
  produce an output without any index (but I guess it will still have
  the sidebar).

> 
>    Indices
>    =======
> 
>    * :ref:`genindex`
> 
> Both of the core-api & driver-api index.rst files do...
> with the difference being that core-api/index.rst has
> one space following ".. only::" while driver-api/index.rst
> has 2 spaces following ".. only::".
> 
> Does that make a difference?

No, I don't think so.

> 
> When looking at the end/bottom of core-api/index.html,
> there is *NO* heading "Indices" and *NO* link "Index" as there
> is in driver-api/index.html.
> Why? 

See above. You'll only see it if you use SPHINXDOCS=core-api.

> There are other cases like this one:
> 
> $ cd Documentation; git grep "^\.\. only:: [^ ]"
> 
> RCU/index.rst:.. only:: subproject and html
> core-api/index.rst:.. only:: subproject and html
> rust/index.rst:.. only:: rustdoc and html
> rust/index.rst:.. only:: not rustdoc and html
> trace/index.rst:.. only:: subproject and html
> virt/index.rst:.. only:: html and subproject
> wmi/devices/index.rst:.. only:: subproject and html

On a side note, I don't like very much this solution, as people can 
forget about that.

Perhaps it would be possible to do it on a different and more automatic
way, by doing some changes at the way partial builds are handled by
sphinx-build-wrapper.

on some brainstorming I did while writing the script, it came to
me that one possibility would be that the wrapper would create a
temporary structure with symlinks to the documents. E.g. when one
does:

	make SPHINXDOCS="peci foo" O=/tmp/build htmldocs

This would create something like:

	$ tree /tmp/build/source
	/tmp/build/source
	├── index.rst
	peci/
	│   ├── index.rst	# Symlink to kernel source file
	│   └── peci.rst	# Symlink to kernel source file
	└── foo/
	    ├── index.rst	# Symlink to kernel source file
	    └── foo.rst		# Symlink to kernel source file

where index.rst would be auto-generated and would contain something like:

	.. SPDX-License-Identifier: GPL-2.0

	.. toctree::
	   :maxdepth: 1

		peci/index
		foo/index

	.. only:: subproject and html

		Indices and tables
		==================

		* :ref:`genindex`

There are some advantages of such approach:

- cross references between multiple SPHINXDIRS will be solved;
- this will speedup such builds, as, right now, the building system
  serializes the build for each directory individually. With such
  approach, it will build everything in parallel;
- this will simplify the logic inside conf.py.

The disadvantages are:
- some extra complexity at the wrapper;
- a new temporary directory will be needed ("/source" on my example)

Comments?

Thanks,
Mauro

Re: confusing ReST/html

[Jani Nikula]

On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> Hi Randy,
>
> Em Tue, 11 Nov 2025 20:59:25 -0800
> Randy Dunlap <rdunlap@infradead.org> escreveu:
>
>> I'm comparing Documentation/core-api/index.{rst,html} and
>> Documentation/driver-api/index.{rst,html}.
>> 
>> Lots (but not all) .rst files end with something like
>> 
>> .. only:: subproject and html
>
> This is related to partial documentation builds.
>
> - On PDF, we don't want to have an "Indices" section. With PDF, LaTeX
>   will always generate an index, outside the "Indices" section, so it
>   ends producing an empty section there.
>
>   That's why the rule has "and html".
>
> - Our building system adds "subproject" when one uses SPHINXDOCS.
>   The above logic ensures that a partial build will have its own index.
>
>   If you want, try to add/remove it and see what happens when building 
>   with SPHINXDOCS. Btw, the quickest one to test is peci:
>
> 	make SPHINXDOCS=peci htmldocs
>
>   If everything is working as expected (I haven't test it for years),
>   on index.rst that contains it, you'll see an index. Removing it will
>   produce an output without any index (but I guess it will still have
>   the sidebar).

:ref:`genindex` creates a *link* to the index, which will be created
regardless of whether you have that link or not.

>
>> 
>>    Indices
>>    =======
>> 
>>    * :ref:`genindex`
>> 
>> Both of the core-api & driver-api index.rst files do...
>> with the difference being that core-api/index.rst has
>> one space following ".. only::" while driver-api/index.rst
>> has 2 spaces following ".. only::".
>> 
>> Does that make a difference?
>
> No, I don't think so.
>
>> 
>> When looking at the end/bottom of core-api/index.html,
>> there is *NO* heading "Indices" and *NO* link "Index" as there
>> is in driver-api/index.html.
>> Why? 
>
> See above. You'll only see it if you use SPHINXDOCS=core-api.
>
>> There are other cases like this one:
>> 
>> $ cd Documentation; git grep "^\.\. only:: [^ ]"
>> 
>> RCU/index.rst:.. only:: subproject and html
>> core-api/index.rst:.. only:: subproject and html
>> rust/index.rst:.. only:: rustdoc and html
>> rust/index.rst:.. only:: not rustdoc and html
>> trace/index.rst:.. only:: subproject and html
>> virt/index.rst:.. only:: html and subproject
>> wmi/devices/index.rst:.. only:: subproject and html
>
> On a side note, I don't like very much this solution, as people can 
> forget about that.

Not only that, but people appear to have cargo cult copy-pasted the
".. only:: subproject and html" bit all over the place for no good
reason.

>
> Perhaps it would be possible to do it on a different and more automatic
> way, by doing some changes at the way partial builds are handled by
> sphinx-build-wrapper.
>
> on some brainstorming I did while writing the script, it came to
> me that one possibility would be that the wrapper would create a
> temporary structure with symlinks to the documents. E.g. when one
> does:
>
> 	make SPHINXDOCS="peci foo" O=/tmp/build htmldocs
>
> This would create something like:
>
> 	$ tree /tmp/build/source
> 	/tmp/build/source
> 	├── index.rst
> 	peci/
> 	│   ├── index.rst	# Symlink to kernel source file
> 	│   └── peci.rst	# Symlink to kernel source file
> 	└── foo/
> 	    ├── index.rst	# Symlink to kernel source file
> 	    └── foo.rst		# Symlink to kernel source file
>
> where index.rst would be auto-generated and would contain something like:
>
> 	.. SPDX-License-Identifier: GPL-2.0
>
> 	.. toctree::
> 	   :maxdepth: 1
>
> 		peci/index
> 		foo/index
>
> 	.. only:: subproject and html
>
> 		Indices and tables
> 		==================
>
> 		* :ref:`genindex`
>
> There are some advantages of such approach:
>
> - cross references between multiple SPHINXDIRS will be solved;
> - this will speedup such builds, as, right now, the building system
>   serializes the build for each directory individually. With such
>   approach, it will build everything in parallel;
> - this will simplify the logic inside conf.py.
>
> The disadvantages are:
> - some extra complexity at the wrapper;
> - a new temporary directory will be needed ("/source" on my example)

You'll get all the error and warning messages referencing some ephemeral
file inside a temp or build directory, which is confusing to say the
least.

> Comments?

When you have problems with Sphinx, you should first try to figure out
the possible solutions in Sphinx, instead of hacking in Makefiles.

In this case, the solution to the index boilerplate is literally half a
dozen lines in conf.py [1].


BR,
Jani.


[1] https://lore.kernel.org/r/cover.1762948491.git.jani.nikula@intel.com


-- 
Jani Nikula, Intel

Re: confusing ReST/html

[Mauro Carvalho Chehab]

On Wed, Nov 12, 2025 at 02:08:50PM +0200, Jani Nikula wrote:
> On Wed, 12 Nov 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > Hi Randy,
> >
> > Em Tue, 11 Nov 2025 20:59:25 -0800
> > Randy Dunlap <rdunlap@infradead.org> escreveu:
> >
> >> I'm comparing Documentation/core-api/index.{rst,html} and
> >> Documentation/driver-api/index.{rst,html}.
> >> 
> >> Lots (but not all) .rst files end with something like
> >> 
> >> .. only:: subproject and html
> >
> > This is related to partial documentation builds.
> >
> > - On PDF, we don't want to have an "Indices" section. With PDF, LaTeX
> >   will always generate an index, outside the "Indices" section, so it
> >   ends producing an empty section there.
> >
> >   That's why the rule has "and html".
> >
> > - Our building system adds "subproject" when one uses SPHINXDOCS.
> >   The above logic ensures that a partial build will have its own index.
> >
> >   If you want, try to add/remove it and see what happens when building 
> >   with SPHINXDOCS. Btw, the quickest one to test is peci:
> >
> > 	make SPHINXDOCS=peci htmldocs
> >
> >   If everything is working as expected (I haven't test it for years),
> >   on index.rst that contains it, you'll see an index. Removing it will
> >   produce an output without any index (but I guess it will still have
> >   the sidebar).
> 
> :ref:`genindex` creates a *link* to the index, which will be created
> regardless of whether you have that link or not.

True, but without the link, genindex won't be accessible from
index.html.

> >
> >> 
> >>    Indices
> >>    =======
> >> 
> >>    * :ref:`genindex`
> >> 
> >> Both of the core-api & driver-api index.rst files do...
> >> with the difference being that core-api/index.rst has
> >> one space following ".. only::" while driver-api/index.rst
> >> has 2 spaces following ".. only::".
> >> 
> >> Does that make a difference?
> >
> > No, I don't think so.
> >
> >> 
> >> When looking at the end/bottom of core-api/index.html,
> >> there is *NO* heading "Indices" and *NO* link "Index" as there
> >> is in driver-api/index.html.
> >> Why? 
> >
> > See above. You'll only see it if you use SPHINXDOCS=core-api.
> >
> >> There are other cases like this one:
> >> 
> >> $ cd Documentation; git grep "^\.\. only:: [^ ]"
> >> 
> >> RCU/index.rst:.. only:: subproject and html
> >> core-api/index.rst:.. only:: subproject and html
> >> rust/index.rst:.. only:: rustdoc and html
> >> rust/index.rst:.. only:: not rustdoc and html
> >> trace/index.rst:.. only:: subproject and html
> >> virt/index.rst:.. only:: html and subproject
> >> wmi/devices/index.rst:.. only:: subproject and html
> >
> > On a side note, I don't like very much this solution, as people can 
> > forget about that.
> 
> Not only that, but people appear to have cargo cult copy-pasted the
> ".. only:: subproject and html" bit all over the place for no good
> reason.
> 
> >
> > Perhaps it would be possible to do it on a different and more automatic
> > way, by doing some changes at the way partial builds are handled by
> > sphinx-build-wrapper.
> >
> > on some brainstorming I did while writing the script, it came to
> > me that one possibility would be that the wrapper would create a
> > temporary structure with symlinks to the documents. E.g. when one
> > does:
> >
> > 	make SPHINXDOCS="peci foo" O=/tmp/build htmldocs
> >
> > This would create something like:
> >
> > 	$ tree /tmp/build/source
> > 	/tmp/build/source
> > 	├── index.rst
> > 	peci/
> > 	│   ├── index.rst	# Symlink to kernel source file
> > 	│   └── peci.rst	# Symlink to kernel source file
> > 	└── foo/
> > 	    ├── index.rst	# Symlink to kernel source file
> > 	    └── foo.rst		# Symlink to kernel source file
> >
> > where index.rst would be auto-generated and would contain something like:
> >
> > 	.. SPDX-License-Identifier: GPL-2.0
> >
> > 	.. toctree::
> > 	   :maxdepth: 1
> >
> > 		peci/index
> > 		foo/index
> >
> > 	.. only:: subproject and html
> >
> > 		Indices and tables
> > 		==================
> >
> > 		* :ref:`genindex`
> >
> > There are some advantages of such approach:
> >
> > - cross references between multiple SPHINXDIRS will be solved;
> > - this will speedup such builds, as, right now, the building system
> >   serializes the build for each directory individually. With such
> >   approach, it will build everything in parallel;
> > - this will simplify the logic inside conf.py.
> >
> > The disadvantages are:
> > - some extra complexity at the wrapper;
> > - a new temporary directory will be needed ("/source" on my example)
> 
> You'll get all the error and warning messages referencing some ephemeral
> file inside a temp or build directory, which is confusing to say the
> least.

True.

> > Comments?
> 
> When you have problems with Sphinx, you should first try to figure out
> the possible solutions in Sphinx, instead of hacking in Makefiles.
> 
> In this case, the solution to the index boilerplate is literally half a
> dozen lines in conf.py [1].

Saw your patch series. Indeed it sounds a better solution. Will do
some tests here.

> 
> 
> BR,
> Jani.
> 
> 
> [1] https://lore.kernel.org/r/cover.1762948491.git.jani.nikula@intel.com
> 
> 
> -- 
> Jani Nikula, Intel

-- 
Thanks,
Mauro