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 %}

Musclor13 · Juillet 5, 2025, 2:04

Bonjour. J’imagine que chaques doc a les mêmes noms de sous-dossiers et fichiers mais dans des dossiers en/fr/de/es… J’autais aussi tendance a dire que tu pourrais creer un “menu” qui aurais des logos/langues/autres en haut de la page et une frame en bas qui afficherais la doc (et si tu change de langue tu te retrouve sur même page de doc mais avec dans un autre dossier (“en” au lieux de “fr”).
Après ce que je dit c’est que de la théorie mais déja si ta doc concerne une appli complexe propose du txt/epub/pdf pour consultation hors ligne ou une aide intégré a ton appli si interface graphique car on a pas toujours internet tout le temps malheureusement (perso je telecharge les docs que je peu pour les lire sur smartphone quand je code sur PC ou tests rapide sur tablette dans le train.

Mindiell · Juillet 7, 2025, 6:45

J’aurais mis le if avant le h3 ;o)

Musclor13 · Juillet 7, 2025, 7:02

J’imagine que la la langue s’affiche même si en-dessous de 1% vu qu’on vérifie après coup… Je peu pas tester maisy a pas longtemps j’ai codé un truc en Rempy et testé le lendemain et entre les indentations mal faites, les fautes de frappes et autre j’avais réussis a avoir 3-4 erreurs sur un truc simple . En vrai faudrais que tu aie une doc dans une langue a 0.9% (même pour le test) voir pourquoi pas une fausse doc pour tester le plus de cas possibles .