Ordnerstruktur

Grundsätzliches und Struktur

Der Inhalt des Kompendiums liegt in Textdateien im Textformat restructuredText (ReST) vor. Diese befinden sich im Unterordner Quelltext und haben die Endung .rst.

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 sehr kurzen und einfachen Dokuments.

Die Textdateien sind, angelehnt an die inhaltliche Gliederung, in einer Ordnerstruktur angeordnet. Die Hauptdatei einer jeden Gliederungsebene heißt index.rst.

Es ergibt sich somit folgende Struktur

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 */
}

Abb. 21 Projektordner und Unterordner: Im Unterordner befinden sich die Quelltextdateien, diese sind gemäß der inhaltlichen Gliederung in Unterordner aufgeteilt

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

Abb. 22 Projektverzeichnis in GitLab™

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

Abb. 23 Der Quelltext-Ordner in GitLab™

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

Abb. 24 Die Dateien und Ordner im Quelltext-Ordner

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

Abb. 25 Die Dateien und Ordner im obersten Ordner

Das Publikationsprojekt „Kompendium des CCCA“ hat einen eigenen Projektordner und mehrere Unterordner. Die wichtigsten Unterordner sind der Quelltext-Ordner und der Export-Ordner.

Im Quelltext-Ordner befinden sich eine oder mehrere Quelltext-Dateien mit dem eigentlichen Inhalt der Publikation. Quelltext-Dateien sind Roh- bzw. Klartext-Dateien, welche ausschließlich Zeichen beinhalten, ohne dirketen Formatierunginformationen oder anderen Objekten (Bilder usw.) – ähnlich einem mittels einer Schreibmaschine erstellten Dokument. Um Formatierungen, Bilder etc. zu ermöglichen und zu integrieren müssen die Quelltextdateien in einem bestimmten Format erstellt werden, dieses wird restructuredText, abgekürzt ResT oder RST, genannt. Diese Dateien werden von einem Programm, dem Compiler namens Sphinx, in ein gewünschtes Ausgabeformat (z. B. PDF für den Druck, HTML für Webseiten, ePub für eBooks, …) übersetzt.

digraph {

"Datei.rst"
        [
                shape = note,
                color=crimson,
                style=filled,
                fillcolor=white,
                fontcolor=crimson,
                fontname="Source Code Pro",
                label="Datei.rst",
        ];
"Compiler"
        [
                shape = box3d,
                color=grey,
                style=filled,
                fillcolor=black,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Compiler\n(Sphinx)",
        ];



"Datei.pdf"
        [
                shape = note,
                color=black,
                style=filled,
                fillcolor=white,
                fontcolor=black,
                fontname="Source Serif Pro",
                label="Datei.pdf",
        ];

"Datei.html"
        [
                shape = note,
                color=blue,
                style=filled,
                fillcolor=white,
                fontcolor=blue,
                fontname="Source Sans Pro",
                label="Datei.html",
        ];
"Datei.epub"
        [
                shape = note,
                color=darkgreen,
                style=filled,
                fillcolor=white,
                fontcolor=darkgreen,
                fontname="Source Sans Pro",
                label="Datei.epub",
        ];

rankdir = TB;

subgraph {
        "Datei.rst" -> "Compiler" -> "Datei.pdf";
        "Compiler" -> "Datei.html";
        "Compiler" -> "Datei.epub";

        # {rank = same; "Datei.rst" ; "Compiler"}
        }
}

Abb. 26 Aus einer Quelltextdatei erzeugt der Compiler unterschiedliche Ausgabedateien und -formate

Die Quelltext-Dateien haben die Endung .rst. Ein einfaches Beispiel wäre folgende Datei index.rst:

index.rst

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

Das ist der Text eines Dokumentes

Gliederung

Ein Publikationsprojekt kann in mehrere Dateien aufgeteilt werden, sinnvollerweise geschieht dies anhand der Gliederungebenen (also z. B. der Kapitel oder unterabschnitte). Somit kann z. B. jedes Kapitel in einer eigenen Datei gespeichert werden. Es gibt dann eine Hauptdatei welche mittels der Direktive .. toctree:: Verweise auf andere Dateien 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) ein.

Eine Kapitel_Datei kann wiederum Verweise auf untergeordnete Abschnitte beinhalten:

Kapitel-1/index.rst

################################
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

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 */
}

Abb. 27 Quelltextordner

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. Dadurch kann die Dokumentenstruktur im Ordnerbaum eines Dateiverwaltungsprogramms (z. B. unter Windows™ dem Explorer oder unter MacOS™ dem Finder) einfach dargestellt werden.

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

Abb. 28 Eine einfache Quelltext-Ordnerstruktur

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

Abb. 29 Eine etwas umfangreichere Quelltext-Ordnerstruktur

Der Quelltext-Ordner dieses Projekts schaut derzeit wie folgt aus (gekürzt):

Quelltext
├── _locales
├── _static
├── _templates
├── _themes
├── Bilder
│   └── Logos
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-150px.png
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-250px.png
│        ├── Ccca-Logo-10-AlmostEuColors-Variante-6-600px.png
│        └── Ccca-LogoBar-4-c-LongerBar.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
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];
}

Abb. 30 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 (/)",
        ];
"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];


}

Abb. 31 Quelltextordner