.. index:: Sphinx .. _Sphinx: Das Dokumentations-System ``sphinx`` ==================================== `Sphinx `__ ist ein in Python geschriebenes Shell-Programm, das aus einer bzw. mehreren Textdateien mit RestructuredText-Syntax auf dem lokalen Rechner wahlweise eine PDF-Datei oder eine beziehungsweise mehrere HTML-Dateien erzeugen kann. [#]_ Da die RestructuredText-Syntax minimal und leicht erlernbar ist, ermöglicht es Sphinx, Dokumente mit nicht einmal dem halben gewöhnlichen Aufwand in einer Online-Version für Webbrowser sowie in einer (druckbaren) PDF-Version zu publizieren. .. _Dursuchen von RST-Dateien: .. rubric:: Dursuchen von RST-Dateien Die Quelldateien eines Sphinx-Projekts sind reine Textdateien mit der Endung ``.rst`` (für RestructuredText); diese lassen sich schnell und einfach nach Inhalten durchsuchen. Persönlich habe ich mir dazu folgende Abkürzung in der Konfigurationsdatei ``~/.zshrc`` definiert: .. code-block:: bash alias rstgrep='find ./ -name "*.rst" | xargs grep' In einer Shell kann damit mittels ``rstgrep Suchbegriff`` nach einem Begriff oder einem regulären Ausdruck in allen ``rst``-Dateien eines Projekts (inklusive aller Unterverzeichnisse) gesucht werden; als Ergebnis bekommt man jede Zeile einer ``rst``-Datei angezeigt, die den Suchbegriff enthält. Durch die Verwendung von :ref:`grep ` können auch reguläre Ausdrücke genutzt werden; beispielsweise würde ``rstgrep "^Hallo *"`` jede Zeile ausgeben, die mit "Hallo" beginnt. Zusätzliche ``grep``-Optionen können ebenfalls wie üblich genutzt werden, würde `rstgrep -li Suchbegriff`` ("list", "ignore-case") anstelle der zutreffenden Zeilen nur die Namen der Dateien auflisten, die den Suchbegriff ohne Berücksichtigung der Groß-/Kleinschreibung enthalten. .. _Installation von Sphinx: .. rubric:: Installation von Sphinx Sphinx sowie einige nützliche Zusatz-Pakete können unter Linux folgendermaßen installiert werden: .. code-block:: bash sudo aptitude install python3-setuptools python3-numpy \ python3-matplotlib python3-docutils dvipng latexmk sudo pip3 Sphinx Mit ``sudo pip3 -U Sphinx`` ("Update") kann Sphinx jederzeit auf den aktuellsten Stand gebracht werden. Zur Erzeugung von PDF-Druckversionen genügt bereits ein minimales LaTeX-System, wie es nach Installation der oben genannten Pakete automatisch vorhanden ist. Um beispielsweise in naturwissenschaftlichen Publikationen einen umfangreichen mathematischen Formelsatz nutzen zu können, sollte bei Bedarf ein :ref:`volles LaTeX-System ` installiert werden. .. toctree:: :maxdepth: 2 quickstart-und-programmaufruf.rst restructuredtext-tutorial.rst anpassungen.rst tinkerer.rst links.rst .. raw:: html
.. only:: html .. rubric:: Anmerkung: .. [#] Um die erzeugten HTML-Dateien im Internet zu publizieren, müssen sie lediglich in einen gemeinsamen Ordner auf einem Webserver kopiert werden. Weist man diesem Ordner anschließend über einen Domain-Anbieter eine feste Webadresse (URL) zu, so ist die Seite bereits fertig! .. `Filezilla `_ oder Midnight Commander