Re: confusing ReST/html

[Jani Nikula <jani.nikula@linux.intel.com>]

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