Re: confusing ReST/html

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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