Variablen in Sphinx-Vorlagen holen

Question

Ich kann nicht herausfinden, wie man über eine Vorlage Variablen in Sphinx-Dokumente bekommt. Ich mache sicherlich einen elementaren Fehler, aber während es viele Dokumentation für die Verwendung von Jinja/Flask-Vorlagen für Web-Service und einige Dokumentation für Sphinx using it gibt, habe ich Probleme, das Folgende zu tun. Vielleicht ist es nicht möglich und ich belle den falschen Baum auf, aber dann ist das ziemlich anders als das, wie Variablen im Allgemeinen in Webvorlagen (im Gegensatz zu Dokumentenvorlagen) funktionieren?

Ich arbeite in einem viel größeren Projekt. Angenommen, in meinem Projekt conf.py ich eine Variable machen, sagen

LANGS = ['en', 'de', 'cn'] 

Ich weiß, dass dies funktioniert, weil, wenn ich die docbuild tun (wir eine benutzerdefinierte docbuild haben, aber ich glaube nicht, es tut etwas wirklich verrückt anderes als eine maßgeschneiderte Logger und eine Reihe von ‚Chatter‘) mit der folgenden Zeile in conf.py

print len(LANGS) 

essen zeigt es während der docbuild auf.

Aber jetzt möchte ich natürlich auf diese Variable in meiner Vorlage zugreifen. Soweit ich das beurteilen kann, überschreiben wir index.rst mit templates/index.html, die von der grundlegenden layout.html für Sphinx erbt. Und wenn ich

<p>We have {{ LANGS|len }} languages</p> 

ich

Wir haben 0 Sprachen

Nun, dies ist seltsam, denn manchmal kann ich einen Fehler in der Build verursachen, indem sie auf Variablen bezieht sich nicht definiert (wenn auch nicht konsistent), so dass es weiß, dass die Variable definiert ist, aber denkt, dass sie die Länge Null hat. Oder hat eine "Null" Variable automatisch die Länge Null?

Wie bekomme ich diese Variable definiert - oder ist das nicht möglich?

Was ich will, ist zu tun, dann in der Liste für jede Sprache etwas tun (eine externe Verbindung machen, insbesondere), aber ich glaube es kein Sinn {% for %}/{% endfor %} bei dem Versuch, oder was auch immer, wenn ich nicht bekommen das funktioniert. Vielleicht implementiert Sphinx nur eine Teilmenge von Jinja?

Wie auch immer, bitte helfen!

Answer 1

Es gibt mindestens zwei Möglichkeiten, Variablen in eine Vorlage zu übergeben:

1. Via html_context:

   Ein Wörterbuch der Werte in den Kontext des Template-Engine für alle Seiten zu übergeben. Mit der Befehlszeilenoption -A von sphinx-build können auch einzelne Werte in dieses Wörterbuch eingefügt werden.

   Beispiel:

   # conf.py: 
   html_context = {'num_langs': len(LANGS)} 
   
   <!-- template: --> 
   <p>We have {{ num_langs }} languages</p> 
   

2. Über die html_theme_options.Dies erfordert das Hinzufügen eine Option theme.conf (Sie können ein Thema erstellen, indem Sie von einem Standard ein Vererbungs):

   [options] 
   num_langs = 1 
   

   Dann können Sie num_langs in conf.py über html_theme_options gesetzt:

   html_theme_options = {'num_langs': len(LANGS)} 
   

   und verwenden Sie es in ein Vorlage:

   <p>We have {{ theme_num_langs }} languages</p>