Sphinx 0.2

Release 0.2 (27. Apr. 2008)

Inkompatible Änderungen

  • Jinja, die Template-Engine, die für die Standard-HTML-Templates verwendet wird, wird nicht mehr mit Sphinx ausgeliefert. Wenn sie nicht automatisch für Sie installiert wird (sie ist nun als Abhängigkeit in setup.py aufgeführt), installieren Sie sie manuell von PyPI. Dies ist auch erforderlich, wenn Sie Sphinx aus einem SVN-Checkout verwenden. In diesem Fall entfernen Sie bitte auch das Verzeichnis sphinx/jinja, das möglicherweise von alten Revisionen übrig geblieben ist.

  • Die umständliche Handhabung des index.html Templates wurde entfernt. Der Konfigurationswert html_index ist weg, und stattdessen sollte html_additional_pages verwendet werden. Wenn Sie es benötigen, ist das alte index.html Template immer noch vorhanden, heißt defindex.html, und Sie können Ihr html_index Template portieren, indem Sie die Jinja-Vererbung verwenden und Ihr Template ändern

    {% extends "defindex.html" %}
{% block tables %}
... old html_index template content ...
{% endblock %}

    und 'index': name ihres templates in html_additional_pages einfügen.

  • Im Layout-Template wurden redundante blocks entfernt; Sie sollten stattdessen den Standardmechanismus von Jinja {{ super() }} verwenden, wie in der (neu geschriebenen) Templating-Dokumentation erklärt.

Neue Funktionen hinzugefügt

  • Erweiterungs-API (Application-Objekt)

    • Unterstützung für eine neue Methode, add_crossref_type. Sie funktioniert wie add_description_unit, aber die Direktive erstellt nur ein Ziel und keine Ausgabe.

    • Unterstützung für eine neue Methode, add_transform. Sie nimmt eine Standard-Docutils Transform Unterklasse, die dann vom Sphinx-Reader beim Parsen von reST-Dokumentbäumen angewendet wird.

    • Unterstützung für andere Template-Engines als Jinja hinzugefügt, indem eine Abstraktion namens "template bridge" hinzugefügt wurde. Diese Klasse kümmert sich um das Rendern von Templates und kann mit dem neuen Konfigurationswert "template_bridge" geändert werden.

    • Die Konfigurationsdatei selbst kann eine Erweiterung sein (wenn sie eine setup() Funktion bereitstellt).

  • Markup

    • Neue Direktive, currentmodule. Sie kann verwendet werden, um den Modulnamen der folgenden dokumentierten Elemente anzugeben, ohne Indexeinträge zu erstellen.

    • Erlaubt die Angabe eines anderen Titels für Dokumente in der toctree.

    • Erlaubt die Angabe mehrerer Optionen in einer cmdoption Direktive.

    • Anzeige von Klassenmitgliedern ohne explizit angegebenen Klassennamen behoben.

  • Templates (HTML-Ausgabe)

    • index.html umbenannt in defindex.html, siehe oben.

    • Es gibt einen neuen Konfigurationswert, html_title, der den Gesamt-"Titel" des Satzes von Sphinx-Dokumenten steuert. Er wird nun überall anstelle von "Projektname vX.Y Dokumentation" verwendet.

    • Alle Verweise auf "Dokumentation" in den Templates wurden entfernt, so dass es mit den Standard-Templates einfacher ist, Sphinx für Nicht-Dokumentations-Dokumente zu verwenden.

    • Templates haben jetzt einen XHTML-DOCTYPE, um mit der HTML-Ausgabe von Docutils konsistent zu sein.

    • Sie können nun eine OpenSearch-Beschreibungsdatei mit dem Konfigurationswert html_use_opensearch erstellen.

    • Sie können jetzt schnell ein Logo in der Seitenleiste einfügen, indem Sie den Konfigurationswert html_logo verwenden.

    • Es gibt neue Blöcke in der Seitenleiste, so dass Sie problemlos Inhalte in die Seitenleiste einfügen können.

  • LaTeX-Ausgabe

    • Das Paket sphinx.sty wurde von unbenutzten Dingen bereinigt.

    • Sie können ein Logo auf der Titelseite mit dem Konfigurationswert latex_logo einfügen.

    • Sie können die Linkfarben sowie eine Rahmen- und Hintergrundfarbe für Verbatim-Umgebungen definieren.

Dank an Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven und Sebastian Wiesner für Vorschläge.

Behobene Fehler

  • sphinx.ext.autodoc: Überprüfe __module__ für explizit angegebene Member nicht. Entferne "self" in der Argumentenliste des Konstruktors.

  • sphinx.htmlwriter: Verwende os.path nicht zum Verbinden von Bild-HREFs.

  • sphinx.htmlwriter: Verwende SmartyPants nicht für HTML-Attributwerte.

  • sphinx.latexwriter: Implementierung von Optionslisten. Außerdem wurden einige andere Änderungen an sphinx.sty vorgenommen, um die Kompatibilität zu verbessern und alte unbenutzte Dinge zu entfernen. Danke an Gael Varoquaux dafür!

  • sphinx.roles: Korrektur der Referenzierung von Glossarbegriffen mit expliziten Zielen.

  • sphinx.environment: Verschlucke keine TOC-Einträge beim Auflösen von Unterbäumen.

  • sphinx.quickstart: Erstelle eine sinnvolle Standardeinstellung für latex_documents.

  • sphinx.builder, sphinx.environment: Behandle einige Benutzerfehlerfälle gracefully.

  • sphinx.util: Folge symbolischen Links bei der Suche nach Dokumenten.