From 73ec59e7a6f4992450934ec17c4edc4574bb6aab Mon Sep 17 00:00:00 2001 From: "Begerad, Stefan" Date: Wed, 17 May 2023 12:05:57 +0200 Subject: [PATCH] feat(delfi): initial commit --- delfi/.gitignore | 6 +++ delfi/Makefile | 25 ++++++++++++ delfi/make.bat | 35 +++++++++++++++++ delfi/readme.md | 88 ++++++++++++++++++++++++++++++++++++++++++ delfi/requirements.txt | 1 + delfi/source/conf.py | 30 ++++++++++++++ delfi/source/index.rst | 21 ++++++++++ delfi/source/intro.md | 43 +++++++++++++++++++++ 8 files changed, 249 insertions(+) create mode 100644 delfi/.gitignore create mode 100644 delfi/Makefile create mode 100644 delfi/make.bat create mode 100644 delfi/readme.md create mode 100644 delfi/requirements.txt create mode 100644 delfi/source/conf.py create mode 100644 delfi/source/index.rst create mode 100644 delfi/source/intro.md diff --git a/delfi/.gitignore b/delfi/.gitignore new file mode 100644 index 0000000..b751e3e --- /dev/null +++ b/delfi/.gitignore @@ -0,0 +1,6 @@ +bundle +build +venv +*.*~ +*~ +*.tar.gz \ No newline at end of file diff --git a/delfi/Makefile b/delfi/Makefile new file mode 100644 index 0000000..6741eb5 --- /dev/null +++ b/delfi/Makefile @@ -0,0 +1,25 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + -rm -rf build + find . -name '*~' -type f -delete + -rm -rf venv diff --git a/delfi/make.bat b/delfi/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/delfi/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/delfi/readme.md b/delfi/readme.md new file mode 100644 index 0000000..2954ae1 --- /dev/null +++ b/delfi/readme.md @@ -0,0 +1,88 @@ +# Introduction + +* setup the project +``` +sphinx-quickstart +``` + +* install Sphinx +``` +https://www.sphinx-doc.org/en/master/usage/installation.html +``` + +* get started with Sphinx +``` +https://www.sphinx-doc.org/en/master/usage/quickstart.html# +``` + +# Build Documentation + +## Python Dependencies + +In order to generate the documentation, +first create a Python virtual environment using the +`venv` module included in Python like this. + +* Create a virtual Python environment in the directory `venv`. +``` +python3 -m venv venv +``` + +* Activate the virtual Python environment. +``` +source venv/bin/activate +``` + +* Install the packages listed in [requirements.txt](./requirements.txt) using `pip`. +``` +pip install -r requirements.txt +``` + +## Running Generator via Make + +Execute make without an argument to see which targets are available +``` +make +``` + +The top level directory contains a Makefile. +Generate HTML output +``` +make html +``` + +Generate PDF output +``` +make latexpdf +``` + +The output files can be found in the subfolder `./build`. + +All generated intermediate artifacts and the final output files can be found in the `./build` subfolder. + +Generate all output +``` +make bundle +``` + +### Clean up + +1. Deactivate the virtual Python environment +``` +deactivate +``` + +2. Clean up the build sources: +``` +make clean +``` + +# File System + +* `build`: build directory +* `Makefile`: build configuration +* `readme.md`: this file +* `source`: source directory +# Links + +* [getting started](https://www.sphinx-doc.org/en/master/usage/quickstart.html) \ No newline at end of file diff --git a/delfi/requirements.txt b/delfi/requirements.txt new file mode 100644 index 0000000..f0694bd --- /dev/null +++ b/delfi/requirements.txt @@ -0,0 +1 @@ +myst-parser diff --git a/delfi/source/conf.py b/delfi/source/conf.py new file mode 100644 index 0000000..edf15e8 --- /dev/null +++ b/delfi/source/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'DELFI' +copyright = '2023, Software Ingenieur Begerad (SIB)' +author = 'Stefan Begerad' +release = '0.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'myst_parser' +] + +templates_path = ['_templates'] +exclude_patterns = ['.*`','*~','*readme.md*'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/delfi/source/index.rst b/delfi/source/index.rst new file mode 100644 index 0000000..becdcb2 --- /dev/null +++ b/delfi/source/index.rst @@ -0,0 +1,21 @@ +.. getting-started documentation master file, created by + sphinx-quickstart on Thu Apr 13 17:31:40 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +(WIP) DELFI: Durchgängige ELektronische FahrgastInformation +=========================================================== + +.. toctree:: + :numbered: + :maxdepth: 3 + :caption: Contents: + + intro + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/delfi/source/intro.md b/delfi/source/intro.md new file mode 100644 index 0000000..8575e3d --- /dev/null +++ b/delfi/source/intro.md @@ -0,0 +1,43 @@ +(intro)= +# Einleitung + +Der Verein [DELFI e.V.](https://delfi.de) +stellt ein Produkt mit dem Namen +[DELFI-Datensatz](https://www.delfi.de/de/leistungen-produkte/daten-dienste/) +über die Plattform +[OpenData ÖPNV](https://opendata-oepnv.de) zur Verfügung. +Dieser Datensatz enthält den ÖPNV, +Schienen-Fernverkehr und Fernbusse für Deutschland. + +Außerdem stellt der Verein ein Produkt mit dem Namen +[Zentrales Haltestellenverzeichnis (ZHV)](https://www.delfi.de/de/leistungen-produkte/daten-dienste/) +über die Plattform +[zhv](https://zhv.wvigmbh.de) zur Verfügung. + +Laut DELFI nutzen Haltestellen im ZHV die +[**DHID: Deutschlandweit einheitliche Haltestellen-ID**](https://de.wikipedia.org/wiki/Haltestelle) +als einen in Deutschland eindeutigen Haltestellen-Bezeichner. +Die DHID ist in dem Dokument +[VDV 432](https://knowhow.vdv.de/documents/432/) +definiert und auch als **Global ID** bekannt. +Bei der Spezifikation **VDV 432** hat sich der +[VDV](https://vdv.de) an dem internationalen +[IFOPT](https://en.wikipedia.org/wiki/Identification_of_Fixed_Objects_in_Public_Transport) +[CEN](https://de.wikipedia.org/wiki/Europ%C3%A4isches_Komitee_f%C3%BCr_Normung) +-Standard orientiert. + +Laut DELFI verwendet auch der DELFI-Datensatz die DHID aus dem ZHV als eindeutigen Haltestellen-Bezeichner. +Für die Umsetzung von diesem Ziel ist DELFI von den Daten-Lieferanten abhängig. +Sie sind es, die Daten an die +[**DELFI-Integrationsplattform (DIP)**](https://www.delfi.de/de/strategie-technik/architektur/) +liefern. +Nur wenn Daten-Lieferanten DHIDs aus dem ZHV als eindeutigen Haltestellen-Bezeichner verwenden, +wird dieser von DELFI in die DIP integriert und pe DELFI-Datensatz exportiert. + +Die Schnittstelle +[delfi.api.swingbe.de](https://v1delfi.api.swingbe.de/stops-not-dhid?oset=1&limit=1) +bietet uns Haltestellen aus dem DELFI-Datensatz an, +welche bisher einen Haltestellen-Bezeichner **nicht** konform zur DHID verwenden. + +Die Webseite [delfi.swingbe.de](https://delfi.swingbe.de) +zeigt uns die Haltestellen dieser Schnittstelle auf einer Karte und Tabelle an. \ No newline at end of file