From 1330a65831e667664ba316244fd46ad9ecce68f5 Mon Sep 17 00:00:00 2001
From: Tobias Klockau <tobias.klockau@deutschebahn.com>
Date: Thu, 5 Oct 2023 17:17:36 +0200
Subject: [PATCH] docs: add description for converting files

---
 docs/source/howtos/1 Converting Files.rst | 37 +++++++++++++++++++++++
 docs/source/index.rst                     |  8 ++---
 2 files changed, 39 insertions(+), 6 deletions(-)
 create mode 100644 docs/source/howtos/1 Converting Files.rst

diff --git a/docs/source/howtos/1 Converting Files.rst b/docs/source/howtos/1 Converting Files.rst
new file mode 100644
index 0000000..3f76987
--- /dev/null
+++ b/docs/source/howtos/1 Converting Files.rst	
@@ -0,0 +1,37 @@
+..
+   Copyright DB Netz AG and contributors
+   SPDX-License-Identifier: Apache-2.0
+
+=============================
+1 Validating Annotation Files
+=============================
+
+Many annotation providers have their own proprietary format, that they use internally. If the project requirements demand the delivery of the data in the RailLabel format, then the `raillabel_providerkit.convert()` method can support you with that.
+
+.. code-block:: python
+
+    from raillabel_providerkit import convert
+    import raillabel
+    import json  # in the case the data is in the json-format
+
+    with open("path/to/source/data.json") as f:
+        raw_data = json.load(f)
+
+    raillabel_scene = convert(raw_data)
+
+    raillabel.save(raillabel_scene, "path/to/target/scene.json")
+
+If you have created a proper loader class for your format in the loader_classes directory, your class should be selected automatically. If not, you should contact our engineers to create one.
+
+In the case, that you do not want to publish your proprietary format, you can also keep your loader class local and provide it as a function parameter. Just make sure your loader class is a child of the `raillabel_providerkit.loader_classes.LoaderABC`-class.
+
+.. code-block:: python
+
+    from raillabel_providerkit import convert
+    import raillabel
+    import json  # in the case the data is in the json-format
+
+    with open("path/to/source/data.json") as f:
+        raw_data = json.load(f)
+
+    raillabel_scene = convert(raw_data, YourLoaderClass)
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d24347d..9898c67 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,7 +6,7 @@
 Welcome to the documentation!
 *****************************
 
-Python RailLabel Development-Kit
+Python RailLabel Provider-Kit
 ================================
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
@@ -17,11 +17,7 @@ Python RailLabel Development-Kit
 
 Description
 -----------
-This library is designed to assist in the handling of the sensor annotations of Deutsche Bahn in the OpenLABEL data format. Common usage for the library:
-
-* fetching specific information from annotation files
-* filtering for specific frames, annotations or objects
-* editing annotation files
+This library is designed to assist annotation partners of DB in providing data, that meets our requirements.
 
 If you want a quickstart at how to use this package, head right into the
 :ref:`how-tos section <howtos>`.