Add software installation

.devcontainer/setup.sh

@@ -46,6 +46,16 @@ fi
 # Install virtual X-Server
 sudo apt-get install -y xvfb
 
+
+### Install mermaid command line tool #########################################
+
+# This is only necessary when building PDFs
+# TODO: Activate this
+
+# apt-get install -y npm
+
+# npm install -g @mermaid-js/mermaid-cli
+
 ### EOF #######################################################################
 
 

.gitignore

@@ -1,23 +1,25 @@
 # In-repository virtual python environment with poetry
-.venv/
+/.venv/
 
 # Tool folder
-.tools/
+/.tools/
 
 # Local (scope is this repository some kind of "virtual" extensions and user settings)
 # Appear when you (cwd is VS Code project's root) start VS Code as
-# $ code --extensions-dir .extensions/ --user-data-dir .user/ --profile profile-$(whoami) .
+#
+# $ code --extensions-dir .extensions/ --user-data-dir .user/ --profile profile-${PWD##*/}-$(whoami) .
+#
 # Advantage: Do not touch your system's VS Code environment. Same as with pipenv
-.extensions/
-.user/
+/.extensions/
+/.user/
 
 # We don't nail down the versions. Let's always get the hottest stuff.
 # We are here at playground phase of a toy project, so no serious release is coming up.
 # Being-up-to-date beats stability and reproducibility here.
 poetry.lock
 
 # Documentation build folder
-out/
+/out/
 
 # Automatically generated files by Sphinx extension create-tags
 _tags/
@@ -32,3 +34,6 @@ esbonio.*
 # Any pycache-files which might appear
 __pycache__/
 *.pyc
+
+# USB-Stick mit Software
+/usb-stick/

.vscode/extensions.json

@@ -27,7 +27,8 @@
         "swyddfa.esbonio",
         "tintinweb.graphviz-interactive-preview",
         "stkb.rewrap",
-        "oderwat.indent-rainbow"
+        "oderwat.indent-rainbow",
+        "scootersoftware.bcompare-vscode"
 
     ]
 }

docs/00-preliminary-meeting/index.rst

@@ -11,7 +11,7 @@ Die Projekttage sind drei Tage lang. Unser Projekt teilt sich in 2 Phasen:
 - :ref:`sec-training-phase` (1. Tag und Vormittag des 2. Tages)
 - :ref:`sec-construction-phase` (Nachmittag des 2. Tages und 3. Tag)
 
-Was die Schüler in den Jahren 2016 und 2018 gemacht haben, könnt Ihr auf der `damaligen Projekt-Seite
+Was die Schüler in den Jahren 2016 und 2018 gemacht haben, könnt ihr auf der `damaligen Projekt-Seite
 <https://basejumpa.wordpress.com/2016/07/06/spassmitelektronik2016/>`__ sehen (ganz am Ende der
 Seite).
 

docs/01-preparation/index.rst

@@ -7,7 +7,7 @@ Vorbereitungen
     :local:
 
 
-Was Ihr braucht
+Was ihr braucht
 ***************
 
 Folgendes braucht jedes Team, um mitarbeiten zu können.
@@ -43,15 +43,15 @@ Weiterhin sollte jedes Team mitbringen:
 
 .. rubric:: Anmerkungen
 
-.. [#] Der Computer benötigt mindestens einen "normalen" USB-Anschluss (USB-A). Falls Ihr nur einen
+.. [#] Der Computer benötigt mindestens einen "normalen" USB-Anschluss (USB-A). Falls ihr nur einen
     ganz modernen Computer mit außschließlich USB-C-Anschlüssen habt, dann bringt bitte einen
     Adapter mit.
 
-.. [#] Man nennt das auch "Administrator-Rechte". Wenn Ihr nicht wisst, ob Ihr die habt, dann schaut
+.. [#] Man nennt das auch "Administrator-Rechte". Wenn ihr nicht wisst, ob ihr die habt, dann schaut
     hilft auch Kapitel :ref:`sec-admin-rights` weiter.
 
 
-Was Ihr bereitgestellt bekommt
+Was ihr bereitgestellt bekommt
 ******************************
 
 ... für die Trainingsphase

docs/02-training-phase/00-software-installieren.rst

@@ -0,0 +1,61 @@
+Zuvor - Software installieren
+#############################
+
+
+Benötigte Software
+******************
+
+Entwicklungsumgebung für Arduino
+    `arduino-ide_2.3.2_Windows_64bit.msi <https://downloads.arduino.cc/arduino-ide/arduino-ide_2.3.2_Windows_64bit.msi>`__ [#]_
+
+
+Treiber für CH340 Chip
+    `CH341SER.ZIP <https://www.wch.cn/downloads/file/5.html?time=2023-03-17%2016:48:51&code=BBZJzJ2kw24QbUa8LUedUzVx4PRkjlwz9evWqUCb?time=2024-07-08%2012:20:04&code=lCVr67G96pyekIQg5857dhQWeOFGZT2tiBPuXn77>`__ [#]_
+
+
+Entweder ladet ihr die Software aus dem Internet über die obigen Links oder von einem der USB-Sticks, die ich mitgebracht habe.
+
+
+Installieren der Software
+*************************
+
+Entwicklungsumgebung für Arduino
+================================
+
+Started das Installationsprogramm `arduino-ide_2.3.2_Windows_64bit.msi` und klickt Euch durch
+aufkommende Dialoge.
+
+
+Treiber für CH340 Chip
+======================
+
+In dem Zip des Treibers ist eine `SETUP.EXE`. Mittels dieser sollte die Installation auf den meisten Laptops funktionieren.
+
+Falls ihr damit die Installation so nicht funktioniert. In diesem Falle muss man (nach Entzippen der Datei) die Installation über den Gerätemanager vornehmen wie folgt:
+
+- Arduino über Kabel an USB anschließen
+- Der Computer teilt mit, dass die Installation nicht funktioniert hat
+- In den Gerätemanager gehen (z.B. über Start, Rechts-click von Computer, dann Kontextmenü Eigenschaften, dort Gerätemanager)
+- Im Gerätemanager sieht man unter Unbekannten Geräten ein Gerät namens USB 2.0 usw. dieses Rechts-Click, dann neuer Treiber. Dann das entzippte Verzeichnis, dort wo die Setup.exe ist, angeben. Dann klappt's mit dem Treiber.
+
+
+Optionale Software
+******************
+
+Bounce2-Bibliothek
+    Für die einfache Flanken-Erkennung bei den Schaltern habe ich in die Entwicklungsumgebung die
+    Bounce2-Bibliothek gleich mit installiert. Diese bekommt ihr von dort
+    https://github.com/thomasfredericks/Bounce2/wiki
+
+Fritzing
+    Die Schaltungen in dieser Doku habe ich mit dem Program "Fritzing" gemacht, das kann man von
+    http://fritzing.org herunterladen.
+
+
+.. rubric:: Anmerkungen
+
+.. [#] ist von der Seite https://www.arduino.cc
+
+.. [#] Der Link ist von der Seite
+    http://www.jens-bretschneider.de/aktuelle-treiber-fur-seriell-zu-usb-adapter/ . Treiber für MacOS,
+    Linux (und auch Windows) sind unter https://sparks.gogo.co.nz/ch340.html verfügbar.

docs/02-training-phase/01-led-anschliessen.rst

@@ -13,7 +13,7 @@ auf dem Steckbrett angebracht, wie auf folgendem Bild dargestellt ist.
 
 .. figure:: _figures/01-led-anschliessen.png
 
-Damit habt Ihr das rote Kabel mit dem 5V-Pin (also dem Pluspol) und das blaue mit dem GND (Steht für
+Damit habt ihr das rote Kabel mit dem 5V-Pin (also dem Pluspol) und das blaue mit dem GND (Steht für
 "ground", das ist englisch für die elektrische "Masse" und ist der Minuspol).
 
 Bei manchen Teams hat die LED sofort geleuchtet, bei anderen nicht.

docs/02-training-phase/02-led-steuern.rst

@@ -76,7 +76,7 @@ Der Befehl
 
 läßt den Arduino genau 1s lang warten. Wenn wir die delays weglassen, dann blinkt die LED schneller als wir es mit dem Auge wahrnehmen können, da der Arduino die Befehle so schnell abarbeitet.
 
-Im Weiteren habt Ihr mehrere LED eingebaut und die Programme entsprechend angepasst. Ihr habt blinkende LEDs und Lauflichter gebaut.
+Im Weiteren habt ihr mehrere LED eingebaut und die Programme entsprechend angepasst. ihr habt blinkende LEDs und Lauflichter gebaut.
 
 Mit einem zu folgendem ähnlichen Programm haben wir die for Schleife kennen gelernt:
 

docs/02-training-phase/index.rst

@@ -3,20 +3,22 @@
 Übungensphase
 #############
 
-Während des Trainings erlernt Ihr, wie Ihr mit dem Arduino und dem Steckbrett umgeht. Dabei fangt
+Während des Trainings erlernt ihr, wie ihr mit dem Arduino und dem Steckbrett umgeht. Dabei fangt
 ihr mit einfachen Dingen an und steigert Euch hin zu komplexeren Inhalten.
 
-Am Ende des Trainings habt Ihr einen Baukasten von Fähigkeiten, die Ihr für Eure eigenes Projekt kombinieren könnt.
+Am Ende des Trainings habt ihr einen Baukasten von Fähigkeiten, die ihr für Eure eigenes Projekt
+kombinieren könnt.
 
-.. figure:: _figures/00-uebersicht.png
+.. drawio-figure:: _figures/00-uebersicht.drawio
     :scale: 50%
 
-    Baukasten der Fähigkeiten [#]_
+    Baukasten der Fähigkeiten [#vin]_
 
 .. toctree::
     :maxdepth: 1
     :hidden:
 
+    00-software-installieren
     01-led-anschliessen
     02-led-steuern
     03-infos-an-computer
@@ -37,4 +39,4 @@ Am Ende des Trainings habt Ihr einen Baukasten von Fähigkeiten, die Ihr für Eu
 
 .. rubric:: Anmerkungen
 
-.. [#] Die mit :kbd:`VIN` gekennzeichneten Fähigkeiten benötigen eine stärkere Stromquelle, als die der Arduino selbst darstellt. Dazu benötigen wir die Erweiterung auf dem Steckbrett und die Powerbank.
+.. [#vin] Die mit :kbd:`VIN` gekennzeichneten Fähigkeiten benötigen eine stärkere Stromquelle, als die der Arduino selbst darstellt. Dazu benötigen wir die Erweiterung auf dem Steckbrett und die Powerbank.

docs/conf.py

@@ -49,18 +49,31 @@
 _print_out_timestamp = f"{_formatted_time} {_current_time.tzname()}"
 _year = _current_time.strftime("%Y")
 
+
+_git_upstream_repo_url = None
+_git_repo_version = ""
+_git_commit_sha_short = "n.a."
+_git_branch = "n.a."
 try:
     _repo = git.Repo(search_parent_directories=True)
-    _git_upstream_repo_url = _repo.remotes.origin.url
-    _git_commit_sha_short = _repo.git.rev_parse(_repo.head.object.hexsha, short=8)
+    try:
+        _git_upstream_repo_url = _repo.remotes.origin.url
+    except:
+        pass
+    try:
+        _git_repo_version = _repo.git.describe(dirty="+")
+    except:
+        pass
+    try:
+        _git_commit_sha_short = _repo.git.rev_parse(_repo.head.object.hexsha, short=8)
+    except:
+        pass
     try:
         _git_branch = _repo.active_branch.name
     except TypeError:
         _git_branch = "detached HEAD"
 except:
-    _git_commit_sha_short = "n.a."
-    _git_branch = "n.a."
-    _git_upstream_repo_url = None
+    pass
 
 _username = getpass.getuser()
 
@@ -71,18 +84,18 @@
 _author = "Some Author"
 if hasattr(conf_project, "author"):
     _author = conf_project.author
-
-_version = open('../VERSION', 'r').readline().strip()
+_commit = _git_repo_version
+if "" == _commit:
+    _commit = _git_commit_sha_short
 
 project   = f"{_project}"
-revision  = f""
 author    = f"{_author}"
 copyright = f"{_year}, {author}"
-release   = f"{_version}"
+
 
 ### Construct meta-data header:
 
-_metadata   = f"version: {_version} | commit: {_git_commit_sha_short} | branch: {_git_branch} | printed at {_print_out_timestamp} by {_username}"
+_metadata   = f"commit: {_commit} | branch: {_git_branch} | printed at {_print_out_timestamp} by {_username}"
 
 ## Add CI information
 # Indicator is the environment variable "BUILD_NUMBER" which is set by the CI/CD system.
@@ -117,10 +130,11 @@
 exclude_patterns = [
 ]
 
-master_doc = "index"
-
+## Let's expand `some string` to `some string` instead of *some string*
 default_role = "code"
 
+master_doc = "index"
+
 numfig = True
 
 
@@ -185,14 +199,12 @@
     if hasattr(conf_project, "color_primary"):
         html_theme_options["color_primary"] = conf_project.color_primary
 
-    html_title = f"{_metadata}"#
-    pass
+    html_title = f"{_metadata}"
 
 elif "classic" == html_theme: #################################################
     html_sidebars = {
         "**": []
     }
-    pass
 
 elif "pydata_sphinx_theme" == html_theme: #####################################
     html_theme_options = {
@@ -241,15 +253,22 @@
 
 plantuml = f"java -jar {_conf_location}/../.tools/plantuml.jar -config {_conf_location}/{_plantuml_config_file}"
 
+plantuml_batch_size = 500
+
 plantuml_output_format = "svg"
 
+plantuml_latex_output_format = "pdf"
+
 
 ### Author diagrams of arbitrary types with "Mermaid" #########################
 # @see https://sphinxcontrib-mermaid-demo.readthedocs.io
 # @see https://mermaid.js.org/syntax/gitgraph.html
 
 extensions.append("sphinxcontrib.mermaid")
 
+# This allows commands other than binary executables to be executed on Windows.
+mermaid_cmd_shell = "True"
+
 
 ### Author diagrams of arbitrary types with "Graphviz" ########################
 # @see https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html