Der Projektordner#

  1. Der Inhalt liegt in Textdateien, welche ausschließlich Zeichen beinhalten, ohne direkten Formatierungen oder andere Objekte (Bilder usw.) – ähnlich einem mittels einer Schreibmaschine erstellten Dokument („Klartext-Dateien“).

  2. Um Formatierungen, Bilder etc. zu ermöglichen werden die Textdateien in einem bestimmten Format erstellt: Dieses wird reStructuredText, abgekürzt reST, genannt.

  3. Die Dateien befinden sich im Ordner Quelltext (bzw. in einem seiner Unterordner) und haben die Endung .rst.

  4. Aus den Textdateien erzeugt ein spezielles Programm (der Compiler namens Sphinx) die fertigen Dateien, je nach gewünschtem Ausgabeformat (PDF für den Druck, HTML für Webseiten, ePub für eBooks, …). Die Textdateien heissen daher auch Quelltext, da sie die einheitliche Inhalts-Quelle für die unterschiedlichen Ausgabeformate darstellen.

  5. Untergeordnete Kapitel/Abschnitte liegen in Unterordnern entsprechend ihrer Hirarchie. Die Inhalte der jeweiligen Gliederungsebene liegen immer in der Datei index.rst.

  6. Der Projektordner und dessen Inhalte werden durch das Versionsverwaltungssystem Git versioniert und in Zweigen (Branches) verwaltet, um paralleles Arbeiten von mehreren Autoren zu ermöglichen.

  7. Branches haben Namen. Als Hauptentwicklungs-Branch wird der Branch master festgelegt. Hier werden alle Beiträge und Änderungen zusammengeführt.

Eine einfache Datei

Ein einfaches Beispiel wäre folgende Datei index.rst:

index.rst: Ein sehr simples ResT-Dokument

################################
Ich bin eine Überschrift
################################

Das ist der Text eines kurzen und einfachen Dokuments.

Man kann Wörter *einfach* oder **sehr stark** hervorheben.

Und natürlich kann man Sachen aufzählen,
zum Beispiel die Zutaten für eine Eierspeise:

-   3 Eier
-   Butter
-   Salz
-   Schnittlauch
digraph { rankdir="LR"; "Projektordner" [ shape=cylinder, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Code Pro", label="RST-Quelltext", width = 2; height = 2; ]; "Sphinx-Compiler" [ shape=cds, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Sphinx-Compiler", ]; "html" [ shape=note, color=mediumblue, fontcolor=mediumblue, fontname="Source Sans Pro", label="Webseite\nHMTL" width = 2; ]; "LaTeX" [ shape=note, color=mediumblue, fontcolor=mediumblue, fontname="Source Code Pro", label="LaTeX\ntex" ]; "LaTeX/Compiler" [ shape=cds, style=filled, fillcolor="#a61017", color="#a61017", fontcolor=white, fontname="Source Sans Pro", label="LaTeX-Compiler" ]; "LaTeX/Compiler/pdf" [ shape=note, color="#a61017", fontcolor="#a61017", fontname="Source Sans Pro", label="Print\nPDF" width = 2; ]; "epub" [ shape=note, color=mediumblue, fontcolor=mediumblue, fontname="Source Sans Pro", label="E-Book\nePUB" width = 2; ]; "Projektordner" -> "Sphinx-Compiler"; "Sphinx-Compiler" -> "html" [color=mediumblue]; "Sphinx-Compiler" -> "epub" [color=mediumblue]; "Sphinx-Compiler" -> "LaTeX" [color=mediumblue]; "LaTeX" -> "LaTeX/Compiler" -> "LaTeX/Compiler/pdf" [color="#a61017"]; {rank = same; "LaTeX/Compiler/pdf"; html; epub; } }

Abb. 2 Aus dem Quelltext erstellt der Compiler Sphinx verschiedene Ausgabeformate#

Gliederung

Um die Verwaltung und Bearbeitung der Textdateien zu vereinfachen werden diese gemäß ihrer inhaltlichen Gliederung in Unterordner strukturiert. Somit wird jedes Kapitel in einer eigenen Datei gespeichert werden. Es gibt dann eine Hauptdatei index.rst welche mittels einer Direktive namens .. toctree:: einen Verweise auf andere untergeordnete Textdateien enthält:

index.rst

################################
Das ist ein Titel
################################

.. toctree::

        Kapitel-1/index.rst

Dieser Text erscheint nach dem 1. Kapitel.

Der Compiler Sphinx fügt beim übersetzen an der entsprechenden Stelle die jeweilige(n) Datei(en) (hier Kapitel-1/index.rst, aber es könnte auch eine Kapitel-2/index.rst und eine Kapitel-3/index.rst geben) ein1.

Diese untergeordneten Dateien können wiederum Verweise auf weiter untergordnete Dateien (also z. B. Kapitel auf Abschnitte, Abschnitte auf Unterabschnitte usw.) enhalten. Die Enstcheidung, bis zu welcher Ebene aufgegliedert wird, erfolgt nach den inhaltlichen Erfordernissen.

1

Wir sehen an dem Beispiel dass die Kapitel-Dateien immer index.rst heißen und in eigenen Ordnern liegen. Dies ist zwar nicht zwingend notwendig, es erleichtert jedoch die Arbeit mit den ausgegliederten Dateien und ist daher empfohlen.

Kapitel-1/index.rst: Eine Kapitel-Datei kann wiederum Verweise auf untergeordnete Abschnitte beinhalten usw.

################################
Das ist Kapitel 1
################################

Dieses Kapitel ist das erste seiner Art.
Es werden im Folgenden Thema 1 und Thema 2
behandelt.

.. toctree::

        Thema-1/index.rst
        Thema-2/index.rst

Es ergibt sich somit folgende Struktur

../../_images/Ordnerstruktur-Basic.png

Abb. 3 Eine einfache Quelltext-Ordnerstruktur#

../../_images/Ordnerstruktur-DieReisenDesMaxMustermann.png

Abb. 4 Eine etwas umfangreichere Quelltext-Ordnerstruktur#

../../_images/ProjectOverview-2020-05-23.png

Abb. 5 Projektverzeichnis der AASS im Webinterface von GitLab™#

../../_images/Ordner-Quelltext-2020-05-23.png

Abb. 6 Der Quelltext-Ordner im Webinterface von GitLab™#

Creative Commons Lizenzvertrag Dieses Werk ist lizenziert unter der Creative Commons Namensnennung - Weitergabe unter gleichen Bedingungen 3.0 Österreich Lizenz (CC BY-SA 3.0 AT). Einzelne Beiträge und Medien können abweichend lizensiert sein.