Dokumentation in erster Version erstellt.

2026-02-19 17:47:03 +01:00
parent 3f0a62405b
commit c00bdd911f
8 changed files with 135 additions and 15 deletions
--- a/README.md
+++ b/README.md
@@ -1,10 +1,12 @@
 # schild2halbjahr

+
 ## Über das Projekt

-Das vorliegende Python Projekt liest u.a. zwei Exportdateien der Schulverwaltungssoftware SchildNRW ein und erzeugt daraus zum einen HTML-Folien mit Schülerleistungsdaten zur Präsentation auf Halbjahreskonferenzen und zum anderen PDF-Dokumente mit Übersichten der Leistungsdaten zum Ausdrucken.
+Das vorliegende Python-Projekt liest u.a. zwei Exportdateien der Schulverwaltungssoftware SchildNRW ein und erzeugt daraus zum einen HTML-Folien mit Schülerleistungsdaten zur Präsentation auf Halbjahreskonferenzen und zum anderen PDF-Dokumente mit Übersichten der Leistungsdaten zum Ausdrucken.

-## beispielinput
+
+## Beispieldaten

 Für eine fiktive Beispielschule mit nur einer Klasse mit drei Schülern habe ich fiktive Leistungsdaten angelegt.

@@ -13,17 +15,26 @@ Hier eine Übersicht der Eingabedateien in Ordner [./beispielinput](./beispielin
 - [SchuelerLeistungsdaten.dat](./beispielinput/SchuelerLeistungsdaten.dat)
 - [SchuelerLernabschnittsdaten.dat](./beispielinput/SchuelerLernabschnittsdaten.dat)
 - [epoche.csv](./beispielinput/epoche.csv)
+ 
+und der Konfigurationsdatei im gleichen Ordner:
+
 - [config.ini](./beispielinput/config.ini)

- Entsprechend hier die Ausgabedateien:
+Entsprechend hier die Ausgabedateien:

- a) HTML-Folien im Ordner [./output/html](./output/html)
+a) HTML-Folien im Ordner [./output/html](./output/html)

 - [folien.html](./output/html/folien.html)
 
- b) PDF-Dokumente im Ordner [./output/pdf](./output/pdf)
+b) PDF-Dokumente im Ordner [./output/pdf](./output/pdf)

 - [ausdruck-farbe.pdf](./output/pdf/ausdruck-farbe.pdf) 
 - [ausdruck-sw.pdf](./output/pdf/ausdruck-sw.pdf) 
 - [uebersichten.pdf](./output/pdf/uebersichten.pdf) 
 
+
+## Beschreibung der Vorgehensweise
+ 
+1. [Erzeugen der Eingabedateien](./doc/dateien.md)
+2. [Konfiguration der Verarbeitung](./doc/konfiguration.md)
+3. [Anstoßen der Verarbeitung](./doc/verarbeitung.md)
--- a/doc/dateien.md
+++ b/doc/dateien.md
@@ -0,0 +1,38 @@
+# Erzeugen der Dateien
+
+
+## Export aus Schild
+
+Rufen Sie SchildNRW auf und rufen Sie den Export „Schnittstelle Schild-NRW“ auf.
+
+Wählen Sie unter "zu exportierende Daten" lediglich die beiden Optionen "Schüler: Leistungsdaten" und "Schüler: Lernabschnittsdaten".
+
+Setzen Sie unter den Optionen den Haken bei "nur sichtbare Einträge exportieren" und "Klasse als zusätzliches Identifikationsmerkmal hinzufügen". Lassen Sie die Option "nur aktuellen Abschnitt exportieren" jedoch unberücksichtigt.
+
+Wählen Sie nun zumindest das aktuelle Schuljahr aus.
+
+Wählen Sie weitere ein bis zwei Vorgängerschuljahre aus, wenn 
+
+- es in Ihrer Datenbank eine/n SchülerIn gibt, der/die im Vorgängerschuljahr eine Wiederholung zum Halbjahr begonnen hat (=> insgesamt zwei Schuljahre exportieren),
+
+- es an Ihrer Schule einen Abiturabschlussjahrgang (Q2 bzw. 13) gibt (=> insgesamt zwei Schuljahre exportieren), 
+
+- in diesem Jahrgang ein/e SchülerIn ein Schuljahr wiederholt hat (=> insgesamt drei Schuljahre exportieren).
+
+Starten Sie den Export. Die dabei erzeugten Dateien 'SchuelerLeistungsdaten.dat' und 'SchuelerLernabschnittsdaten.dat' werden später benötigt.
+
+
+## Epochenunterricht
+
+Bei oben beschriebenen Schild Export werden leide Fächer nicht gekennzeichnet, die nur im ersten Halbjahr unterrichtet und deren Note automatisch ins zweite Halbjahr übertragen wird (Epochenuterricht).
+
+Um die Fächer dennoch auf den Konferenzfolien zu kennzeichnen, können sie in einer Datei 'epoche.csv' aufgelistet werden. Die Angabe dieser Datei ist optional.
+
+Hier eine selbsterklärende Beispieldatei in den Beispieldaten (vgl. Datei [epoche.csv](../beispielinput/epoche.csv)):
+
+'''
+Klasse|Fächer
+09A|GE
+'''
+
+Listen Sie hier zeilenweise aller Klassen und die zugehörige Fachbezeichnung mit Epochenunterricht auf. Hat eine Klasse mehrere Fächer in Epochenunterricht, so listen Sie alle Fächer in einer Zeile durch Komma getrennt auf.
--- a/doc/konfiguration.md
+++ b/doc/konfiguration.md
@@ -0,0 +1,26 @@
+# Konfiguration der Verarbeitung
+
+Für die Verarbeitung stehen Ihnen einige Parameter zur Verfügung, die in der Datei 'config.ini' festgelegt werden.
+
+Sie finden hier ein selbsterklärendes Beispiel (vgl. Datei [config.ini](../beispielinput/config.ini)):
+
+'''
+[Allgemein]
+schuljahr = 2025
+halbjahr = 2
+
+[Jahrgänge]
+jahrgänge_oberstufe = EF,Q1,Q2
+jahrgang_einführung = EF
+jahrgang_abitur = Q2
+als_eine_Klasse = EF
+ignoriere_Jahrgänge =
+'''
+
+Im allgemeinen oberen Teil werden Schuljahr (z.B. 2025 für 2025/2026) und Halbjahr (1 oder 2) eingestellt.
+
+Im unteren Teil werden die Jahrgänge bezeichnet, die zur Oberstufe gehören, die die Einführungsphase und das letzte Jahr der Qualifikationsphase bilden. Haben Sie keine Oberstufe, können Sie die Angaben einfach so belassen. (Bitte nicht löschen, das führt zu Fehlermeldungen!).
+
+Haben Sie einen Jahrgang (oftmals EF), in der zwar Klassen gebildet werden (EFa usw.), auf der Konferenz aber der Jahrgang nicht klassenweise gezeigt werden soll, können Sie dies bei 'als_eine_Klasse' festlegen.
+
+Sollen Jahrgänge ignoriert werden, listen Sie diese durch Komma getrennt unter 'ignoriere_Jahrgänge' auf.
--- a/doc/verarbeitung.md
+++ b/doc/verarbeitung.md
@@ -0,0 +1,45 @@
+# Anstoßen der Verarbeitung
+
+
+## a) Zusammenstellen des Eingabeverzeichnisses
+
+Das Pythonskript sucht im Ordner 'schild2halbjahr' nach einem Verzeichnis 'input/'. Ist dies nicht vorhanden, wird das Verzeichnis 'beispielinput/' für die Verarbeitung verwendet.
+
+Legen Sie also - sofern noch nicht vorhanden - das Unterverzeichnis 'input/' an und fügen Sie die bereits erzeugten bzw. erstellten Dateien 'SchuelerLeistungsdaten.dat', 'SchuelerLernabschnittsdaten.dat', 'epoche.csv' (optional) und 'config.ini' in diesem Verzeichnis ab.
+
+
+## b) Voraussetzungen
+
+Um das Skript zu starten sind einige Voraussetzungen zu erfüllen:
+
+1. Auf dem eingesetzten Rechner muss [Python](https://www.python.org) auf der Kommandozeile installiert sein. (Das vorliegende Skript wurde unter Python 3.13 entwickelt und getestet. Es sollte aber auch mit älteren Python Versionen lauffähig sein.) Da Python plattformunabhängig ist, ist auch das vorliegende Projekt plattformunabhängig.
+
+2. Das Python-Modul ``xhtml2pdf`` muss installiert sein.
+
+```python
+pip3 install xhtml2pdf
+```
+
+
+## c) Starten des Skripts
+
+Nun kann das Skript auf der Kommandozeile gestartet werden. Dazu muss es aus dem Skriptverzeichnis heraus gestartet werden.
+
+```
+python3 konferenz.py
+```
+
+Auf der Konsole werden die Verarbeitungsschritte dokumentiert und auch evtl. Fehler bei der Verarbeitung angezeigt:
+
+```
+Eingabeverzeichnis input/ existiert nicht, verarbeite beispielinput/ ...
+Lese die Daten ein...
+Erzeuge HTML-Folien...
+Erzeuge PDF-Ausdruck in Farbe...
+Erzeuge PDF-Ausdruck in SW...
+Erzeuge PDF-Notenübersichten für die SI...
+Fertig!
+```
+
+Die Ausgabedateien werden in den Ordnern 'output/html/' und '/output/pdf/' erzeugt bzw. aktualisiert.
+
--- a/output/html/folien.html
+++ b/output/html/folien.html
@@ -21,7 +21,7 @@
 	</head>
 	<body>

-        <div class="reveal">            <div class="slides"><section><h2>Noten 2025/26, 2. Hj.</h2><p class="index"><a href="#klasse-09A">9A</a></p><p class="time">Erzeugt: Do. 19. Februar 2026, 16:20 Uhr</p></section><section id="klasse-09A">
+        <div class="reveal">            <div class="slides"><section><h2>Noten 2025/26, 2. Hj.</h2><p class="index"><a href="#klasse-09A">9A</a></p><p class="time">Erzeugt: Do. 19. Februar 2026, 17:44 Uhr</p></section><section id="klasse-09A">
 <h1>Klasse 9A</h1>
 </section>
 <section>
--- a/output/pdf/ausdruck-farbe.pdf
+++ b/output/pdf/ausdruck-farbe.pdf
@@ -57,7 +57,7 @@ endobj
 endobj
 10 0 obj
 <<
-/Author () /CreationDate (D:20260219162051+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219162051+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
+/Author () /CreationDate (D:20260219174458+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219174458+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
  /Subject () /Title () /Trapped /False
 >>
 endobj
@@ -113,7 +113,7 @@ endobj
 /Filter [ /ASCII85Decode /FlateDecode ] /Length 370
 >>
 stream
-GasJMb>&+)&4Q?b'mHWHMQZ5'4,jdf`e:/d!$?_76/i#Vin%Bk'6M%RFCl:Oh7$.M@MiBU^X"Fg\mRL+Yb94VNZ?1^`hds!VYY=Wg3RejRYWAHU'X]crqO_TGi!?FZ,nnMHo)bdLM@urcQ6X$p-R%-h((._QLq8E*)6V\jEDH<Y',B&qt4Rp"u5+m&hY>\gEiDc/5\#RkTq\LZnbF,-P%A_8UO.eJ[9sHU`PQ33D]uZai.hK2Y4YU,\$#j2(7!Ejrb./%=qcGkWC6sI:@%@?QIer=oZ?sULaCV<tB<qS^jmFc;e`*3HjK6F2r]>I,'1r[YrB92erJ-_IWAiDBIWh&9Isn7UklVg3sR+(Yrj0bnkjMJQM~>endstream
+GasJMb>&+)&4Q?b'mHWHMQZ5'4,jdf`e:/d!$?_76/i#Vin%Bk'6M%RFCl:Oh7$.M@MiBU^X"Fg\mRL+Yb94VNZ?1^`hds!VYY=Wg3RejRYWAHU'X]crqO_TGi!?FZ,nnMHo)bdLM@urcQ6X$p-R%-h((._QLq8E*)6V\jEDH<Y',B&qt4Rp"u5+m&hY>\gEiDc/5\#RkTq\LZnbF,-P%A_8UO.eJ[9sHU`PQ33D]uZai.hK2Y4YU,\$#j2(7!Ejrb./%=qcGkWC6sI:@%@?QIer=oZ?sULaCV<tB<qS^jmFc;e`*3HjK6F2r]>I,'1r[YrB92erJ-_IWAiDBIWh&9Isn8'^)P[J_.50=oa@RP01eJR8~>endstream
 endobj
 21 0 obj
 <<
@@ -149,7 +149,7 @@ xref
 trailer
 <<
 /ID 
-[<3f3ff014c16c08f3dde7d7fe6476e5ce><3f3ff014c16c08f3dde7d7fe6476e5ce>]
+[<665582cec76cf26472f5c20e635aa03e><665582cec76cf26472f5c20e635aa03e>]
 % ReportLab generated PDF document -- digest (http://www.reportlab.com)

 /Info 10 0 R
--- a/output/pdf/ausdruck-sw.pdf
+++ b/output/pdf/ausdruck-sw.pdf
@@ -57,7 +57,7 @@ endobj
 endobj
 10 0 obj
 <<
-/Author () /CreationDate (D:20260219162051+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219162051+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
+/Author () /CreationDate (D:20260219174458+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219174458+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
  /Subject () /Title () /Trapped /False
 >>
 endobj
@@ -113,7 +113,7 @@ endobj
 /Filter [ /ASCII85Decode /FlateDecode ] /Length 370
 >>
 stream
-GasJMb>&+)&4Q?b'mHWHMQZ5'4,jdf`e:/d!$?_76/i#Vin%Bk'6M%RFCl:Oh7$.M@MiBU^X"Fg\mRL+Yb94VNZ?1^`hds!VYY=Wg3RejRYWAHU'X]crqO_TGi!?FZ,nnMHo)bdLM@urcQ6X$p-R%-h((._QLq8E*)6V\jEDH<Y',B&qt4Rp"u5+m&hY>\gEiDc/5\#RkTq\LZnbF,-P%A_8UO.eJ[9sHU`PQ33D]uZai.hK2Y4YU,\$#j2(7!Ejrb./%=qcGkWC6sI:@%@?QIer=oZ?sULaCV<tB<qS^jmFc;e`*3HjK6F2r]>I,'1r[YrB92erJ-_IWAiDBIWh&9Isn7UklVg3sR+(Yrj0bnkjMJQM~>endstream
+GasJMb>&+)&4Q?b'mHWHMQZ5'4,jdf`e:/d!$?_76/i#Vin%Bk'6M%RFCl:Oh7$.M@MiBU^X"Fg\mRL+Yb94VNZ?1^`hds!VYY=Wg3RejRYWAHU'X]crqO_TGi!?FZ,nnMHo)bdLM@urcQ6X$p-R%-h((._QLq8E*)6V\jEDH<Y',B&qt4Rp"u5+m&hY>\gEiDc/5\#RkTq\LZnbF,-P%A_8UO.eJ[9sHU`PQ33D]uZai.hK2Y4YU,\$#j2(7!Ejrb./%=qcGkWC6sI:@%@?QIer=oZ?sULaCV<tB<qS^jmFc;e`*3HjK6F2r]>I,'1r[YrB92erJ-_IWAiDBIWh&9Isn8'^)P[J_.50=oa@RP01eJR8~>endstream
 endobj
 21 0 obj
 <<
@@ -149,7 +149,7 @@ xref
 trailer
 <<
 /ID 
-[<f7ba3b6ad577900a7ad83b635a2d1dc0><f7ba3b6ad577900a7ad83b635a2d1dc0>]
+[<e2e5e8debf9228f6c2a667dd7c424246><e2e5e8debf9228f6c2a667dd7c424246>]
 % ReportLab generated PDF document -- digest (http://www.reportlab.com)

 /Info 10 0 R
--- a/output/pdf/uebersichten.pdf
+++ b/output/pdf/uebersichten.pdf
@@ -32,7 +32,7 @@ endobj
 endobj
 6 0 obj
 <<
-/Author () /CreationDate (D:20260219162051+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219162051+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
+/Author () /CreationDate (D:20260219174458+01'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260219174458+01'00') /Producer (xhtml2pdf <https://github.com/xhtml2pdf/xhtml2pdf/>) 
  /Subject () /Title () /Trapped /False
 >>
 endobj
@@ -62,7 +62,7 @@ xref
 trailer
 <<
 /ID 
-[<8ad35963ec9228149a1f07063ac42b71><8ad35963ec9228149a1f07063ac42b71>]
+[<2d4f1165f8a0617194cfd4e942da00e7><2d4f1165f8a0617194cfd4e942da00e7>]
 % ReportLab generated PDF document -- digest (http://www.reportlab.com)

 /Info 6 0 R