Documentation multi langue alabaster

yabb85 · Novembre 17, 2024, 10:22

Bonjour,

J’essaie de faire une documentation qui contient plusieurs langues avec sphinx et le thème alabaster. j’arrive bien à générer chaque langue, mais je n’ai rien pour passer de l’une a l’autre. C’est soit je génère une langue, soit l’autre mais pas les deux en même temps.
Savez-vous comment ajouter un moyen de passer d’une langue a l’autre dans la documentation générée?
Merci

mdk · Novembre 17, 2024, 2:03

Côté docs.python.org on a sorti un bazooka :

c’est un script qui lance un sphinx-build par langue (et par version de Python mais ce n’est pas ton sujet).

Ensuite pour permettre à l’utilisateur de passer de l’une a l’autre, on a mis un petit “placeholder” dans le HTML, et au chargement de la page on replace le placeholder par un menu :

github.com

python/docsbuild-scripts/blob/b2b548353b50a3316ba098b89382fe6b8f8474a9/templates/switchers.js#L180


      
            const languages = _ALL_LANGUAGES;
          
            document
              .querySelectorAll(".version_switcher_placeholder")
              .forEach((placeholder) => {
                const s = _create_version_select(versions);
                s.addEventListener("change", _on_version_switch);
                placeholder.append(s);
              });
          
            document
              .querySelectorAll(".language_switcher_placeholder")
              .forEach((placeholder) => {
                const s = _create_language_select(languages);
                s.addEventListener("change", _on_language_switch);
                placeholder.append(s);
              });
          };
          
          if (document.readyState !== "loading") {
            _initialise_switchers();

Ça s’est sédimentarisé dans notre thème :

github.com

python/python-docs-theme/blob/185e4f8cb6a6833bfcaa1e73fc29fcbaeb524ccf/python_docs_theme/layout.html#L20


      
              <a href="{{ pathto(rellink[0])|e }}" title="{{ rellink[1]|striptags|e }}"
                 {{ accesskey(rellink[2]) }}>{{ rellink[3] }}
              </a>
              {%- if not loop.first %}{{ reldelim2 }}{% endif %}
          </li>
          {%- endfor %}
          {%- block rootrellink %}
          <li><img src="{{ pathto('_static/' ~ theme_root_icon, 1) }}" alt="{{ theme_root_icon_alt_text }}" style="vertical-align: middle; margin-top: -1px"/></li>
          <li><a href="{{theme_root_url}}">{{theme_root_name}}</a>{{ reldelim1 }}</li>
          <li class="switchers">
            <div class="language_switcher_placeholder"></div>
            <div class="version_switcher_placeholder"></div>
          </li>
          <li>
              {% if theme_root_include_title %}
              <a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}
              {% endif %}
          </li>
          {%- endblock %}
            {%- for parent in parents %}
                <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>

mais j’imagine que pour alabaster tu peux soit surcharger un peu le thème pour glisser ce que tu veux à coup de templates_path, soit rédiger du js qui se débrouille a poser son menu sans placeholder dans le HTML.

J’espère qu’il y a des solutions plus élégantes en 2024

yabb85 · Novembre 17, 2024, 11:10

Meric beaucoup pour la piste.
Je suis bien parti sur templates_path et j’ai customisé alabaster en rajoutant un petit template. Et un un html_context dans le fichier conf.py pour definir les url pour chaques langues.

voici mon template:

<h3>{{ _('Langues') }}</h3>                                
{% if languages|length >= 1 %}                             
    <ul>                                                   
        {% for the_language, url in languages %}           
        <li><a href="{{ url }}">{{ the_language }}</a></li>
        {% endfor %}                                       
    </ul>                                                  
{% endif %}