Sphinx FAQ

Dies ist eine Liste häufig gestellter Fragen zu Sphinx. Bitte schlagen Sie neue Einträge vor!

Wie kann ich…

… PDF-Dateien ohne LaTeX erstellen?

rinohtype bietet einen PDF-Builder, der als direkter Ersatz für den LaTeX-Builder verwendet werden kann.

… Abschnittsnummern erhalten?

Diese sind in der LaTeX-Ausgabe automatisch; für HTML geben Sie eine Option :numbered: an die Direktive toctree, wo Sie mit der Nummerierung beginnen möchten.

… das Aussehen der generierten HTML-Dateien anpassen?

Verwenden Sie Themes, siehe HTML-Theming.

… globale Substitutionen oder Includes hinzufügen?

Fügen Sie sie in den Konfigurationswerten rst_prolog oder rst_epilog hinzu.

… den gesamten TOC-Baum in der Seitenleiste anzeigen?

Verwenden Sie das toctree-Callable in einer benutzerdefinierten Layout-Vorlage, wahrscheinlich im Block sidebartoc.

… eine eigene Erweiterung schreiben?

Siehe die Tutorials.

… meine bestehenden Dokumente von MoinMoin-Markup konvertieren?

Der einfachste Weg ist die Konvertierung in xhtml, dann die Konvertierung von xhtml zu reStructuredText. Sie müssen immer noch Klassen und ähnliches markieren, aber die Überschriften und Codebeispiele werden sauber übernommen.

Für viele weitere Erweiterungen und andere beigesteuerte Inhalte siehe das Repository sphinx-contrib.

Sphinx verwenden mit…

Read the Docs

Read the Docs ist ein Dokumenten-Hosting-Service, der auf Sphinx basiert. Sie hosten Sphinx-Dokumentation und unterstützen eine Reihe weiterer Funktionen, darunter Versionsunterstützung, PDF-Generierung und mehr. Der Leitfaden Erste Schritte ist ein guter Einstiegspunkt.

Epydoc

Es gibt eine Drittanbieter-Erweiterung, die eine API-Rolle bereitstellt, die auf Epydocs API-Dokumentation für eine gegebene Kennung verweist.

Doxygen

Michael Jones hat eine reStructuredText/Sphinx-Brücke zu Doxygen namens breathe entwickelt.

SCons

Glenn Hutchings hat ein SCons-Build-Skript geschrieben, um Sphinx-Dokumentation zu erstellen; es wird hier gehostet: https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel hat einen Setuptools-Befehl geschrieben, der Sphinx-Dokumentation automatisch in den PyPI-Bereich für Paketdokumentation unter https://pythonhosted.org/ hochlädt.

GitHub Pages

Fügen Sie sphinx.ext.githubpages zu Ihrem Projekt hinzu. Es ermöglicht Ihnen, Ihre Dokumentation auf GitHub Pages zu veröffentlichen. Es generiert automatisch Hilfsdateien für GitHub Pages beim Erstellen von HTML-Dokumenten.

MediaWiki

Siehe sphinx-wiki, ein Projekt von Kevin Dunn.

Google Analytics

Sie können eine benutzerdefinierte Vorlage layout.html verwenden, wie hier

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script>
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'XXX account number XXX']);
  _gaq.push(['_trackPageview']);
</script>
{% endblock %}

{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script>
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'https://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}
Google Suche

Um die integrierte Suchfunktion von Sphinx durch Google Suche zu ersetzen, gehen Sie wie folgt vor

  1. Gehen Sie zu https://#/cse/all, um den Google Such-Codeausschnitt zu erstellen.

  2. Kopieren Sie den Codeausschnitt und fügen Sie ihn in _templates/searchbox.html in Ihrem Sphinx-Projekt ein

    <div>
   <h3>{{ _('Quick search') }}</h3>
   <script>
      (function() {
         var cx = '......';
         var gcse = document.createElement('script');
         gcse.async = true;
         gcse.src = 'https://#/cse.js?cx=' + cx;
         var s = document.getElementsByTagName('script')[0];
         s.parentNode.insertBefore(gcse, s);
      })();
   </script>
  <gcse:search></gcse:search>
</div>

  3. Fügen Sie searchbox.html zum Konfigurationswert html_sidebars hinzu.

Sphinx vs. Docutils

tl;dr: docutils konvertiert reStructuredText in mehrere Ausgabeformate. Sphinx baut auf docutils auf, um die Erstellung von Querverweisen und indizierten Dokumenten zu ermöglichen.

docutils ist ein Textverarbeitungssystem zur Konvertierung von einfacher Textdokumentation in andere, reichhaltigere Formate. Wie in der docutils-Dokumentation erwähnt, verwendet docutils Reader zum Lesen eines Dokuments, Parser zum Parsen von einfacher Textformatierung in eine interne Baumstruktur, die aus verschiedenen Arten von Nodes besteht, und Writer zum Ausgeben dieses Baums in verschiedenen Dokumentformaten. docutils bietet Parser für ein einfaches Textformat – reStructuredText – obwohl andere, Out-of-Tree-Parser implementiert wurden, einschließlich Sphinx' Markdown-Parser. Auf der anderen Seite bietet es Writer für viele verschiedene Formate, einschließlich HTML, LaTeX, Manpages, Open Document Format und XML.

docutils stellt seine gesamte Funktionalität über eine Vielzahl von Frontend-Tools bereit, wie z. B. rst2html, rst2odt und rst2xml. Entscheidend ist jedoch, dass all diese Tools und docutils selbst sich mit einzelnen Dokumenten befassen. Sie unterstützen keine Konzepte wie Querverweise, Indexierung von Dokumenten oder die Erstellung einer Dokumentenhierarchie (die sich typischerweise in einem Inhaltsverzeichnis manifestiert).

Sphinx baut auf docutils auf, indem es die Reader und Parser von docutils nutzt und seine eigenen Builder bereitstellt. Infolgedessen umschließt Sphinx einige der von docutils bereitgestellten Writer. Dies ermöglicht Sphinx, viele Funktionen bereitzustellen, die mit docutils einfach nicht möglich wären, wie die oben genannten.

Epub-Informationen

Die folgende Liste gibt einige Hinweise zur Erstellung von EPUB-Dateien

  • Teilen Sie den Text in mehrere Dateien auf. Je länger die einzelnen HTML-Dateien sind, desto länger dauert es, bis der E-Book-Reader sie rendert. In extremen Fällen kann das Rendern bis zu einer Minute dauern.

  • Versuchen Sie, die Markierung zu minimieren. Das zahlt sich auch bei der Renderzeit aus.

  • Für einige Reader können Sie eingebettete oder externe Schriftarten mit der CSS-Direktive @font-face verwenden. Dies ist äußerst nützlich für Code-Auflistungen, die oft am rechten Rand abgeschnitten werden. Die Standard-Courier-Schriftart (oder Variante) ist ziemlich breit und Sie können nur bis zu 60 Zeichen pro Zeile anzeigen. Wenn Sie sie durch eine schmalere Schriftart ersetzen, können Sie mehr Zeichen pro Zeile erhalten. Sie können sogar FontForge verwenden und schmale Varianten einer freien Schriftart erstellen. In meinem Fall erhalte ich bis zu 70 Zeichen pro Zeile.

    Möglicherweise müssen Sie ein wenig experimentieren, bis Sie brauchbare Ergebnisse erzielen.

  • Testen Sie die erstellten EPUBs. Sie können verschiedene Alternativen verwenden. Die mir bekannten sind Epubcheck, Calibre, FBreader (obwohl es CSS nicht rendert) und Bookworm. Für Bookworm können Sie den Quellcode von https://code.google.com/archive/p/threepress herunterladen und Ihren eigenen lokalen Server ausführen.

  • Große schwebende Divs werden nicht richtig angezeigt. Wenn sie mehr als eine Seite bedecken, wird das Div nur auf der ersten Seite angezeigt. In diesem Fall können Sie die Datei epub.css aus dem Verzeichnis sphinx/themes/epub/static/ in Ihr lokales Verzeichnis _static/ kopieren und die Float-Einstellungen entfernen.

  • Dateien, die außerhalb der toctree-Direktive eingefügt werden, müssen manuell eingebunden werden. Dies gilt manchmal für Anhänge, z. B. das Glossar oder die Indizes. Sie können sie mit der Option epub_post_files hinzufügen.

  • Die Handhabung der EPUB-Titelseite unterscheidet sich vom reStructuredText-Verfahren, das Bildpfade automatisch auflöst und die Bilder in das Verzeichnis _images legt. Für die EPUB-Titelseite legen Sie das Bild in das Verzeichnis html_static_path und referenzieren Sie es mit seinem vollständigen Pfad in der Konfigurationsoption epub_cover.

  • Der Befehl kindlegen kann aus einer erstellten epub3-Datei in eine .mobi-Datei für Kindle konvertieren. Sie erhalten ihrDokument.mobi unter _build/epub nach dem folgenden Befehl

    $ make epub
$ kindlegen _build/epub/yourdoc.epub

    Der kindlegen-Befehl akzeptiert keine Dokumente, die Abschnittsüberschriften um die toctree-Direktive herum haben

    Section Title
=============

.. toctree::

   subdocument

Section After Toc Tree
======================

    kindlegen geht davon aus, dass alle Dokumente linear geordnet sind, aber das resultierende Dokument hat eine komplizierte Reihenfolge für kindlegen

    ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``

    Wenn Sie die folgende Fehlermeldung erhalten, korrigieren Sie Ihre Dokumentenstruktur

    Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.

Texinfo-Informationen

Es gibt zwei Hauptprogramme zum Lesen von Info-Dateien: info und GNU Emacs. Das Programm info hat weniger Funktionen, ist aber in den meisten Unix-Umgebungen verfügbar und kann schnell vom Terminal aus aufgerufen werden. Emacs bietet eine bessere Schrift- und Farbdarstellung und unterstützt umfangreiche Anpassungen (natürlich).

Hinweise

Die folgenden Hinweise können hilfreich sein, wenn Sie Texinfo-Dateien erstellen möchten

  • Jeder Abschnitt entspricht einem anderen node in der Info-Datei.

  • Doppelpunkte (:) können in Menüeinträgen und Xrefs nicht richtig maskiert werden. Sie werden durch Semikolons (;) ersetzt.

  • Links zu externen Info-Dateien können mit dem etwas offiziellen URI-Schema info erstellt werden. Zum Beispiel:

    info:Texinfo#makeinfo_options