docs: translations: add translations links when they exist
authorVegard Nossum <vegard.nossum@oracle.com>
Fri, 15 Dec 2023 12:37:01 +0000 (13:37 +0100)
committerJonathan Corbet <corbet@lwn.net>
Tue, 19 Dec 2023 21:34:59 +0000 (14:34 -0700)
commit7418ec5b151f5591f750d57705cbb633c084a434
treeb71cbd2cafa0603546979d7cf205423dea8f3a51
parentdcd39fa2be95efd5cbce74661151f68510cb67fe
docs: translations: add translations links when they exist

Add a new Sphinx extension that knows about the translations of kernel
documentation and can insert links to the translations at the top of
the document.

It basically works like this:

1. Register a new node type, LanguagesNode.

2. Register a new transform, TranslationsTransform, that inserts a new
   LanguageNode at the top of every document. The LanguageNode contains
   "pending references" to translations of the document. The key here
   is that these are pending (i.e. unresolved) references that may or
   may not actually exist.

3. Register a 'doctree-resolved' event that iterates over all the
   LanguageNode nodes. Any unresolved references are filtered out; the
   list of resolved references is passed to the 'translations.html'
   template and rendered as an HTML node (if HTML output is selected).

Testing: make htmldocs, make latexdocs with Sphinx v4.3.2 and Firefox.

v2:
- changed bar into a drop-down menu
- fixed language labels
- fixed hysteresis reported by Akira Yokosawa

Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: Yanteng Si <siyanteng@loongson.cn>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com
Documentation/conf.py
Documentation/sphinx-static/custom.css
Documentation/sphinx/templates/translations.html [new file with mode: 0644]
Documentation/sphinx/translations.py [new file with mode: 0644]