.. index:: single: Projektordner .. _Thema-Projektordner: 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 :program:`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** :program:`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. .. rubric:: Eine einfache Datei Ein einfaches Beispiel wäre folgende Datei ``index.rst``: .. admonition:: ``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 .. graphviz:: :caption: Aus dem Quelltext erstellt der Compiler *Sphinx* verschiedene Ausgabeformate 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; } } .. rubric:: 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 :samp:`.. toctree::` einen Verweise auf andere untergeordnete Textdateien enthält: .. admonition:: ``index.rst`` :: ################################ Das ist ein Titel ################################ .. toctree:: Kapitel-1/index.rst Dieser Text erscheint nach dem 1. Kapitel. Der Compiler :program:`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) ein\ [#fn-indexrst]_. 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. .. [#fn-indexrst] 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. .. admonition:: ``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 .. figure:: /Bilder/Ordnerstruktur-Basic.png Eine einfache Quelltext-Ordnerstruktur .. figure:: /Bilder/Ordnerstruktur-DieReisenDesMaxMustermann.png Eine etwas umfangreichere Quelltext-Ordnerstruktur .. figure:: /Bilder/Screenshots/Gitlab/ProjectOverview-2020-05-23.png Projektverzeichnis der AASS im Webinterface von GitLab™ .. figure:: /Bilder/Screenshots/Gitlab/Ordner-Quelltext-2020-05-23.png :width: 100% Der ``Quelltext``-Ordner im Webinterface von GitLab™ .. Der Quelltext-Ordner dieses Projekts schaut derzeit wie folgt aus (gekürzt):: Quelltext ├── _locales ├── _static ├── _templates ├── _themes ├── Bilder │   └── Logos │   ├── Logo-1.png │   ├── Logo-2.png │   └── Logo-3.svg ├── Git │   └── index.rst ├── GitLab │   └── index.rst ├── Konventionen │   └── index.rst ├── Organisation │   └── index.rst ├── Projektordner │   └── index.rst ├── Rst │   └── index.rst ├── Sphinx │   └── index.rst ├── UebersichtSpp │   └── index.rst ├── conf.py └── index.rst ----- .. .. graphviz:: :caption: Projektordner und Unterordner: Im Unterordner befinden sich die Quelltextdateien, diese sind gemäß der inhaltlichen Gliederung in Unterordner aufgeteilt graph { "Projektordner" [ shape=folder, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="CCCA-Kompendium", ]; "Quelltext (/)" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Quelltext (/)", ]; "/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-1", ]; "/Kapitel-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; "/Kapitel-1/Thema-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-1", ]; "/Kapitel-1/Thema-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; "/Kapitel-1/Thema-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-2", ]; "/Kapitel-1/Thema-2/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; rankdir = TB; subgraph { "Projektordner" -- "Quelltext (/)"; "Quelltext (/)" -- "/index.rst" [color=coral]; "Quelltext (/)" -- "/Kapitel-1" [color=mediumblue]; "/Kapitel-1" -- "/Kapitel-1/index.rst" [color=coral]; "/Kapitel-1" -- "/Kapitel-1/Thema-1" [color=mediumblue]; "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst" [color=coral]; "/Kapitel-1" -- "/Kapitel-1/Thema-2" [color=mediumblue]; "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst" [color=coral]; "/index.rst" -- "/Kapitel-1/index.rst" [style=dotted] ; "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-1/index.rst" [style=dotted] ; "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-2/index.rst"[style=dotted] ; {rank = same; "Quelltext (/)"; "/index.rst";} {rank = same; "/Kapitel-1"; "/Kapitel-1/index.rst";} } /* closing subgraph */ } .. .. graphviz:: :caption: Quelltextordner graph { "Projektordner" [ shape=folder, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="Projektordner", ]; "Quelltext (/)" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Quelltext (/)", ]; "/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-1", ]; "/Kapitel-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; "/Kapitel-1/Thema-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-1", ]; "/Kapitel-1/Thema-1/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; "/Kapitel-1/Thema-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-2", ]; "/Kapitel-1/Thema-2/index.rst" [shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst"]; rankdir = TB; subgraph { "Projektordner" -- "Quelltext (/)"; "Quelltext (/)" -- "/index.rst" [color=coral]; "Quelltext (/)" -- "/Kapitel-1" [color=mediumblue]; "/Kapitel-1" -- "/Kapitel-1/index.rst" [color=coral]; "/Kapitel-1" -- "/Kapitel-1/Thema-1" [color=mediumblue]; "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst" [color=coral]; "/Kapitel-1" -- "/Kapitel-1/Thema-2" [color=mediumblue]; "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst" [color=coral]; "/index.rst" -- "/Kapitel-1/index.rst" [style=dotted] ; "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-1/index.rst" [style=dotted] ; "/Kapitel-1/index.rst" -- "/Kapitel-1/Thema-2/index.rst"[style=dotted] ; {rank = same; "Quelltext (/)"; "/index.rst";} {rank = same; "/Kapitel-1"; "/Kapitel-1/index.rst";} } /* closing subgraph */ } .. .. graphviz:: :caption: Die Ordnerstruktur graph { "Projektordner" [ shape=folder, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="Projektordner", ]; "Quelltext (/)" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Quelltext (/)", ]; "index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Bilder" [shape=folder, color=purple, fontcolor=purple fontname="Source Sans Pro", label="Bilder"]; "/Kapitel-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-1", ]; "/Kapitel-1/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1/Thema-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-1", ]; "/Kapitel-1/Thema-1/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1/Thema-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-2", ]; "/Kapitel-1/Thema-2/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-...", ]; "/Kapitel-2/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-3" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-...", ]; "/Kapitel-3/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "Export" [ shape=folder, color=forestgreen, style=filled, fillcolor=forestgreen, fontcolor=white, fontname="Source Sans Pro", ]; "Export/branch" [ shape=folder, color=forestgreen, style=filled, fillcolor=forestgreen, fontcolor=white, fontname="Source Sans Pro", label="branch"]; "Export/branch/html" [ shape=folder, color=forestgreen, style=filled, fillcolor=forestgreen, fontcolor=white, fontname="Source Sans Pro", label="html" ]; "Export/branch/epub" [ shape=folder, color=forestgreen, style=filled, fillcolor=forestgreen, fontcolor=white, fontname="Source Sans Pro", label="epub" ]; "Export/branch/latex" [ shape=folder, color=forestgreen, style=filled, fillcolor=forestgreen, fontcolor=white, fontname="Source Sans Pro", label="latex" ]; "Projektordner" -- "Quelltext (/)"; "Quelltext (/)" -- "index.rst" [color=mediumblue]; "Quelltext (/)" -- "/Bilder" [color=mediumblue]; "Quelltext (/)" -- "/Kapitel-1" [color=mediumblue]; "/Kapitel-1" -- "/Kapitel-1/index.rst" [color=crimson]; "/Kapitel-1" -- "/Kapitel-1/Thema-1" [color=mediumblue]; "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst" [color=crimson]; "/Kapitel-1" -- "/Kapitel-1/Thema-2" [color=mediumblue]; "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst" [color=crimson]; "Quelltext (/)" -- "/Kapitel-2" [color=mediumblue]; "/Kapitel-2" -- "/Kapitel-2/index.rst" [color=crimson]; "Quelltext (/)" -- "/Kapitel-3" [color=mediumblue]; "/Kapitel-3" -- "/Kapitel-3/index.rst" [color=crimson]; "Projektordner" -- "Export"; "Export" -- "Export/branch" [color=forestgreen]; "Export/branch" -- "Export/branch/html" [color=forestgreen]; "Export/branch" -- "Export/branch/epub" [color=forestgreen]; "Export/branch" -- "Export/branch/latex" [color=forestgreen]; } .. .. graphviz:: :caption: Quelltextordner graph { "Projektordner" [ shape=folder, color=black, style=filled, fillcolor=grey, fontcolor=black, fontname="Source Sans Pro", label="Projektordner", ]; "Quelltext (/)" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Quelltext (/)", ]; "Export" [ shape=folder, color="#ccffcc", style=filled, fillcolor="#ccffcc", fontcolor=white, fontname="Source Sans Pro", ]; "/conf.py" [ shape=note, color=grey, fontcolor=grey, fontname="Source Sans Pro", label="conf.py" ]; "/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-1", ]; "/Kapitel-1/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1/Thema-1" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-1", ]; "/Kapitel-1/Thema-1/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-1/Thema-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Thema-2", ]; "/Kapitel-1/Thema-2/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Kapitel-2" [ shape=folder, color=mediumblue, style=filled, fillcolor=mediumblue, fontcolor=white, fontname="Source Sans Pro", label="Kapitel-...", ]; "/Kapitel-2/index.rst" [ shape=note, color=crimson, fontcolor=crimson, fontname="Source Sans Pro", label="index.rst" ]; "/Bilder" [ shape=folder, color=purple, style=filled, fillcolor=purple, fontcolor=white, fontname="Source Sans Pro", label="Bilder", ]; "Projektordner" -- "Quelltext (/)"; "Projektordner" -- "Export" [ color="#ccffcc"; ]; "Quelltext (/)" -- "/index.rst" [color=crimson]; "Quelltext (/)" -- "/conf.py" [color=grey]; "Quelltext (/)" -- "/Bilder" [color=purple]; "Quelltext (/)" -- "/Kapitel-1" [color=mediumblue]; "/Kapitel-1" -- "/Kapitel-1/index.rst" [color=crimson]; "/Kapitel-1" -- "/Kapitel-1/Thema-1" [color=mediumblue]; "/Kapitel-1/Thema-1" -- "/Kapitel-1/Thema-1/index.rst" [color=crimson]; "/Kapitel-1" -- "/Kapitel-1/Thema-2" [color=mediumblue]; "/Kapitel-1/Thema-2" -- "/Kapitel-1/Thema-2/index.rst" [color=crimson]; "Quelltext (/)" -- "/Kapitel-2" [color=mediumblue]; "/Kapitel-2" -- "/Kapitel-2/index.rst" [color=crimson]; }