Sphinx 0.5

Release 0.5.2 (24. März 2009)

  • Korrekte Maskierung von | in der LaTeX-Ausgabe.

  • #71: Wenn ein Dekodierungsfehler in Quellendateien auftritt, wird eine Warnung ausgegeben und die Zeichen durch „?“ ersetzt.

  • Behebung eines Problems bei der HTML-Suche, wenn die Indexierung zu lange dauert.

  • Keine Ausgabe von Systemmeldungen während der Auflösung, da diese auch dann in den Doctrees verbleiben würden, wenn `keep_warnings` auf `false` gesetzt ist.

  • #82: Ermittlung des korrekten Pfads für von docutils genannte Abhängigkeiten. Dies behebt ein Verhalten, bei dem eine Quelle mit abhängigen Dateien immer als geändert gemeldet wurde.

  • Erkennung von `toctree`-Direktiven, die nicht auf der obersten Ebene einer Sektion, sondern innerhalb von Blockelementen wie Tabellen stehen.

  • Verwendung einer neuen RFC-Basis-URL, da rfc.org anscheinend ausgefallen ist.

  • Behebung eines Absturzes bei der `todolist`-Direktive, wenn keine Todo-Elemente definiert sind.

  • Kein wiederholtes Aufrufen von LaTeX oder dvipng, wenn diese einmal nicht gefunden wurden; stattdessen wird in diesem Fall textbasiertes LaTeX als Ersatz verwendet.

  • Behebung von Problemen mit Fußnoten in der LaTeX-Ausgabe.

  • Verhinderung, dass doppelte Bindestriche in Code-Literalen in der LaTeX-Ausgabe zu Halbgeviertstrichen werden.

  • Öffnen von `literalinclude`-Dateien im Universal-Newline-Modus, um beliebige Zeilenumbruchkonventionen zuzulassen.

  • Die Option -Q funktioniert jetzt tatsächlich.

  • #86: Behebung expliziter Dokumenttitel in Toctrees.

  • #81: Schreiben von Umgebung und Suchindex auf eine Weise, die vor Ausnahmen während des Dumps geschützt ist.

  • #80: Behebung von `UnicodeErrors`, wenn eine Locale mit `setlocale()` gesetzt ist.

Release 0.5.1 (15. Dez. 2008)

  • #67: Ausgabe von Warnungen über fehlgeschlagene Doctests in der `doctest`-Erweiterung, auch im Quiet-Modus.

  • #72: In `pngmath` wird es möglich, in Windows einen vollständigen Pfad zu LaTeX und dvipng anzugeben. Dazu werden die Optionen pngmath_latex und pngmath_dvipng nicht mehr in Befehl und zusätzliche Argumente aufgeteilt; verwenden Sie pngmath_latex_args und pngmath_dvipng_args, um zusätzliche Argumente anzugeben.

  • Kein Absturz bei fehlgeschlagenen Doctests mit Nicht-ASCII-Zeichen.

  • Kein Absturz beim Schreiben von Statusmeldungen und Warnungen, die nicht kodierbare Zeichen enthalten.

  • Warnung, wenn ein `doctest`-Erweiterungsblock keinen Code enthält.

  • Behebung der Handhabung von `:param:`- und `:type:`-Doc-Feldern, wenn diese Markup (insbesondere Cross-Referenz-Rollen) enthalten.

  • #65: Behebung der Speicherung von Tiefeninformationen für PNGs, die von der `pngmath`-Erweiterung generiert wurden.

  • Behebung eines Absturzes von `autodoc`, wenn `automethod` außerhalb eines Klassenkontexts verwendet wird.

  • #68: Korrektur der LaTeX-Ausgabe für Bilder mit angegebener Höhe.

  • #60: Behebung eines falschen generierten Bildpfads beim Einbinden von Bildern in Quellen in Unterverzeichnissen.

  • Behebung der JavaScript-Suche, wenn `html_copy_source` auf `false` gesetzt ist.

  • Behebung eines Einrückungsproblems in `autodoc`, wenn Klassen mit der Option autoclass_content = "both" dokumentiert werden.

  • Kein Absturz bei leeren Indexeinträgen, nur eine Warnung ausgeben.

  • Behebung eines Tippfehlers im JavaScript-Suchcode, der die Suchfunktion in einigen Konfigurationen unbrauchbar machte.

Release 0.5 (23. Nov. 2008) – Geburtstags-Release!

Neue Funktionen hinzugefügt

  • Markup-Funktionen

    • Zitate sind jetzt global: Alle Zitate, die in beliebigen Dateien definiert sind, können aus jeder Datei referenziert werden. Zitate werden für die LaTeX-Ausgabe in einem Literaturverzeichnis gesammelt.

    • Fußnoten werden jetzt korrekt im LaTeX-Builder behandelt: Sie erscheinen an der Stelle der Fußnotenreferenz im Text, nicht am Ende eines Abschnitts. Dank an Andrew McNamara für den ursprünglichen Patch.

    • „System Message“-Warnungen werden nun automatisch aus der erstellten Dokumentation entfernt und nur nach stderr geschrieben. Wenn Sie das alte Verhalten wünschen, setzen Sie den neuen Konfigurationswert keep_warnings auf True.

    • Glossareinträge werden jetzt automatisch in den Index aufgenommen.

    • Abbildungen mit Bildunterschriften können nun wie Abschnittsüberschriften referenziert werden, indem die `:ref:`-Rolle ohne expliziten Linktext verwendet wird.

    • Die Rolle cmember wurde zur Konsistenz hinzugefügt.

    • Listen, die mit Buchstaben oder römischen Ziffern nummeriert sind, werden jetzt wie in Standard-reST behandelt.

    • Die Direktive seealso kann nun auch Argumente erhalten, als Kurzform.

    • Sie können nun mehrere Programme und deren Optionen mit der neuen Direktive program dokumentieren.

  • HTML-Ausgabe und Templates

    • Inkompatible Änderung: Der „Root“-Beziehungslink (oben links in der Relbar) verweist nun standardmäßig auf master_doc, nicht mehr auf ein Dokument namens „index“. Das alte Verhalten war zwar in einigen Situationen nützlich, aber etwas unerwartet. Überschreiben Sie den „rootrellink“-Block im Template, um anzupassen, worauf er verweist.

    • Die JavaScript-Suche sucht nun zuerst nach Objekten, bevor sie im Volltext sucht.

    • TOC-Baum-Einträge haben nun CSS-Klassen, die es ermöglichen, sie je nach Tiefe zu stylen.

    • Hervorgehobene Codeblöcke haben nun CSS-Klassen, die es ermöglichen, sie je nach Sprache zu stylen.

    • HTML-``-Tags über die Docutils meta-Direktive werden nun unterstützt.

    • SerializingHTMLBuilder wurde als neuer abstrakter Builder hinzugefügt, der als Basisklasse für die Serialisierung von erstelltem HTML in einem spezifischen Format dienen kann. PickleHTMLBuilder ist eine konkrete Unterklasse davon, die pickle als Serialisierungsimplementierung verwendet.

    • JSONHTMLBuilder wurde als weitere SerializingHTMLBuilder-Unterklasse hinzugefügt, die das generierte HTML in JSON-Dateien für die weitere Verarbeitung speichert.

    • Der Block rellinks im Layout-Template heißt nun linktags, um Verwechslungen mit den Relbar-Links zu vermeiden.

    • Die HTML-Builder haben nun zwei zusätzliche Attribute, die verwendet werden können, um die Erstellung von Anker-Links nach Überschriften und Definitions-Links zu deaktivieren.

    • Es wird nur dann ein Modulindex generiert, wenn sich einige Module in der Dokumentation befinden.

  • Neue und geänderte Konfigurationswerte

    • Unterstützung für Internationalisierung in generiertem Text wurde mit den Konfigurationswerten language und locale_dirs hinzugefügt. Vielen Dank an die Sprachbeitragenden

      • Horst Gutmann – Deutsch

      • Pavel Kosina – Tschechisch

      • David Larlet – Französisch

      • Michał Kandulski – Polnisch

      • Yasushi Masuda – Japanisch

      • Guillem Borrell – Spanisch

      • Luc Saffre und Peter Bertels – Niederländisch

      • Fred Lin – Traditionelles Chinesisch

      • Roger Demetrescu – Brasilianisches Portugiesisch

      • Rok Garbas – Slowenisch

    • Der neue Konfigurationswert highlight_language setzt einen globalen Standard für die Hervorhebung. Wenn 'python3' ausgewählt ist, werden Konsolenausgabe-Blöcke wie bei 'python' erkannt.

    • Die Lexer-Erkennung von Pygments wurde als Hervorhebungs-„Sprache“ guess exponiert.

    • Der neue Konfigurationswert latex_elements ermöglicht es, alle LaTeX-Schnipsel zu überschreiben, die Sphinx standardmäßig in die generierte .tex-Datei einfügt.

    • Der Konfigurationswert exclude_dirnames wurde hinzugefügt, mit dem z.B. CVS-Verzeichnisse aus der Suche nach Quelldateien ausgeschlossen werden können.

    • Der Konfigurationswert source_encoding wurde hinzugefügt, um die Eingabekodierung auszuwählen.

  • Erweiterungen

    • Die neuen Erweiterungen sphinx.ext.jsmath und sphinx.ext.pngmath bieten mathematische Unterstützung für HTML- und LaTeX-Builder.

    • Die neue Erweiterung sphinx.ext.intersphinx erstellt halbautomatisch Links zur Sphinx-Dokumentation von Python-Objekten in anderen Projekten.

    • Die neue Erweiterung sphinx.ext.todo ermöglicht das Einfügen von „To do“-Direktiven, deren Sichtbarkeit in der Ausgabe umgeschaltet werden kann. Sie fügt auch eine Direktive hinzu, um eine Liste aller Todo-Elemente zu kompilieren.

    • sphinx.ext.autodoc hat ein neues Event autodoc-process-signature, das die Abstimmung der Funktionssignatur-Introspektion ermöglicht.

    • sphinx.ext.autodoc hat ein neues Event autodoc-skip-member, das die Abstimmung, welche Mitglieder in den generierten Inhalt aufgenommen werden, ermöglicht.

    • Beachtung von __all__ beim automatischen Dokumentieren von Modulmitgliedern.

    • Die automodule-Direktive unterstützt nun die Optionen synopsis, deprecated und platform.

  • Erweiterungs-API

    • Sphinx.add_node() nimmt nun optionale Besucher-Methoden für die HTML-, LaTeX- und Text-Translator entgegen; dies erspart das manuelle Patchen der Klassen.

    • Hinzugefügt wurde Sphinx.add_javascript(), womit Skripte hinzugefügt werden, die im Standard-HTML-Template geladen werden.

    • Neue Events hinzugefügt: source-read, env-updated, env-purge-doc, missing-reference, build-finished.

  • Weitere Änderungen

    • Ein Kommandozeilenschalter -Q wurde hinzugefügt: er unterdrückt Warnungen.

    • Ein Kommandozeilenschalter -A wurde hinzugefügt: er kann verwendet werden, um zusätzliche Werte in die HTML-Templates einzufügen.

    • Ein Kommandozeilenschalter -C wurde hinzugefügt: wenn er angegeben wird, ist keine Konfigurationsdatei conf.py erforderlich.

    • Ein distutils-Befehl build_sphinx wurde hinzugefügt: Wenn Sphinx installiert ist, können Sie für Projekte mit Sphinx-Dokumentation python setup.py build_sphinx aufrufen. Dies erstellt die Dokumentation und platziert sie im Standard-Distutils-Build-Verzeichnis.

    • Im Quickstart-Modus wird bei der Auswahl eines Root-Verzeichnisses, das bereits ein Sphinx-Projekt enthält, eine Fehlermeldung ausgegeben und der Vorgang abgebrochen.

Behobene Fehler

  • #51: Maskierung von Konfigurationswerten, die in HTML-Templates eingefügt werden.

  • #44: Behebung kleinerer Probleme bei der Generierung des HTML-Hilfeindexes.

  • Behebung der LaTeX-Ausgabe für Zeilenblöcke in Tabellen.

  • #38: Behebung des Fehlers „illegal unit“ bei Verwendung von Pixelbreiten/-höhen für Bilder.

  • Unterstützung von Tabellenunterschriften in der LaTeX-Ausgabe.

  • #39: Umgehung eines Fehlers in Jinja, der dazu führte, dass „<generator …>“ in der HTML-Ausgabe erschien.

  • Behebung eines Problems mit Modul-Links, die nicht in der LaTeX-Ausgabe generiert wurden.

  • Behebung der Handhabung von Bildern in verschiedenen Verzeichnissen.

  • #29: Unterstützung von Optionslisten im Text-Writer. Sicherstellen, dass Striche, die lange Optionsnamen einleiten, nicht zu Halbgeviertstrichen werden.

  • Unterstützung der Option „scale“ für Bilder in der HTML-Ausgabe.

  • #25: Korrektes Maskieren von Anführungszeichen in Attributwerten von HTML-Hilfen.

  • Behebung des LaTeX-Builds für einige Beschreibungs-Umgebungen mit :noindex:.

  • #24: Kein Absturz bei ungewöhnlicher Groß-/Kleinschreibung von Rollennamen (wie :Class:).

  • ANSI-Farben nur auf Farb-Terminals ausgeben.

  • Aktualisierung auf die neueste Version von `fncychap.sty`, um Probleme mit Nicht-ASCII-Zeichen am Anfang von Kapiteltiteln zu beheben.

  • Behebung eines Problems mit der Indexgenerierung in der LaTeX-Ausgabe, das durch das nicht zuletzt eingebundene `hyperref` verursacht wurde.

  • Rückgabe-Annotationen für Funktionen ohne Parameter nicht ignorieren.

  • Labels für Codeblöcke nicht verwerfen.