1. Einführung

Dieser Text dient als Anleitung zum Schreiben von Berichten für das Studium mit dem Programm Sphinx (https://www.sphinx-doc.org). Gerne dürfen Sie diesen Text aus gitlab „clonen“ und für Ihre Bedürfnisse anpassen.

Das Grundprinzip von Sphinx ist, dass man den Text als gewöhnlichen „ASCII-Text“ in einem vertrauten Editor schreibt (das darf auch ein Programmier-Editor wie Vim, Emacs, Sublime, Atom, Visual Studio Code … sein). Der Text wird mit „Markup“ Anweisungen versehen, die später die Darstellung steuern, z.B. wird die Anweisung „Wort zwischen Sternen“ in kursive Schrift umgesetzt (*auffällig* wird also zu auffällig).

Vermutlich lesen Sie diesen Text im HTML Format in einem Web Browser. Dann sollte irgendwo auf der Seite ein Link mit dem Namen „View page source“ oder ähnlich sein, der zum rohen Text mit den Markup-Anweisungen führt. Beim voreingestellten Stil Alabaster ist der Link unten rechts („Page source“), beim optionalen Read-the-Docs Thema ist der Link oben rechts auf der Seite.

Dieser Text hat vier Teile. Der erste Teil befasst sich damit, wie man Sphinx verwendet. Der zweite Teil enthält ein paar Tipps zum Schreiben. Der dritte Teil zeigt einige Werkzeuge, die zum Schreiben eines Berichtes nützlich sein können. Dabei geht es um Vektorzeichnungen, Verdrahtungsdiagramme, Schaltpläne, Platinenpläne, Plots, die serielle Schnittstelle und die Programmiersprachen C und Python im Allgemeinen. Der vierte Teil beschäftigt sich mit Anpassungen, die sie an diesem Demo-Bericht machen müssen, damit Sie daraus einen Bericht für Ihre Veranstaltung bekommen.

Neu hinzugekommen ist eine Anleitung, wie man die erzeugten HTML Seiten auf den Web-Space der Hochschule übertragen kann (siehe Abschnitt 4.7).

Der Text wendet sich eher an Leute, die Linux auf ihrem Rechner verwenden. Alle Programme funktionieren aber auch unter Windows und MAC-OSX, wenn auch mit leicht unterschiedlicher Handhabung, z.B. wird aus dem Linux make unter Windows eine make.bat.

Tipps und Ergänzungen zu diesem Text schicken Sie mir am besten per E-mail an <Hubert.Hoegl@hs-augsburg.de>.