• Vegard Nossum's avatar
    docs: translations: add translations links when they exist · 7418ec5b
    Vegard Nossum authored
    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: default avatarVegard Nossum <vegard.nossum@oracle.com>
    Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
    Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com
    7418ec5b
translations.html 365 Bytes