Re: [PATCH] Documentation: use a source-read extension for the index link boilerplate

[Jonathan Corbet <corbet@lwn.net>]

Jani Nikula <jani.nikula@intel.com> writes:

> The root document usually has a special :ref:`genindex` link to the
> generated index. This is also the case for Documentation/index.rst. The
> other index.rst files deeper in the directory hierarchy usually don't.
>
> For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
> but some other index.rst in the hierarchy. Currently they have a
> ".. only::" block to add the index link when doing SPHINXDIRS html
> builds.
>
> This is obviously very tedious and repetitive. The link is also added to
> all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
> root document.
>
> Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
> include it at the end of the root document for subproject builds in an
> ad-hoc source-read extension defined in conf.py.
>
> For now, keep having the boilerplate in translations, because this
> approach currently doesn't cover translated index link headers.
[...]
>  101 files changed, 30 insertions(+), 685 deletions(-)

Whee ... I do like that!

This patch, when applied after Mauro's massive python-doc series, causes
the build to crash, since he renamed "doctree".  So I've taken the
liberty of applying it with this tweak.

Thanks,

jon

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 74ae78b6c510..7e246101630f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -595,7 +595,7 @@ def add_subproject_index(app, docname, content):
 
     # Add the index link at the root of translations, but not at the root of
     # individual translations. They have their own language specific links.
-    rel = os.path.relpath(app.srcdir, start=doctree).split('/')
+    rel = os.path.relpath(app.srcdir, start=kern_doc_dir).split('/')
     if rel[0] == 'translations' and len(rel) > 1:
         return
 
@@ -604,7 +604,7 @@ def add_subproject_index(app, docname, content):
         return
 
     # The include directive needs a relative path from the srcdir
-    rel = os.path.relpath(os.path.join(doctree, 'sphinx-includes/subproject-index.rst'), start=app.srcdir)
+    rel = os.path.relpath(os.path.join(kern_doc_dir, 'sphinx-includes/subproject-index.rst'), start=app.srcdir)
 
     content[0] += f'\n.. include:: {rel}\n\n'