doc: start XML tutorial

docs/source/tutorial/configuration.md

@@ -30,12 +30,30 @@ from pyrekordbox.config import update_config
 update_config(pioneer_install_dir, pioneer_app_dir)
 ````
 
+## Configuration files
 Alternatively the two paths can be specified in a configuration file under the section
 `rekordbox`. Supported configuration files are pyproject.toml, setup.cfg, rekordbox.toml,
 rekordbox.cfg and rekordbox.yml.
 
+**pyproject.toml** / **pyrekordbox.toml**
+`````toml
+[pyrekordbox]
+pioneer-install-dir = "C:/Program Files/Pioneer"
+pioneer-app-dir = "C:/Users/user/AppData/Roaming/Pioneer"
+`````
+
+
+**setup.cfg** / **pyrekordbox.cfg**
+`````ini
+[pyrekordbox]
+pioneer-install-dir = C:/Program Files/Pioneer
+pioneer-app-dir = C:/Users/user/AppData/Roaming/Pioneer
+`````
+
+
+**rekordbox.yml**
 ````yaml
 rekordbox:
-  pioneer-install-dir: C:\Program Files\Pioneer
-  pioneer-app-dir: C:\Users\user\AppData\Roaming\Pioneer
+  pioneer-install-dir: C:/Program Files/Pioneer
+  pioneer-app-dir: C:/Users/user/AppData/Roaming/Pioneer
 ````

docs/source/tutorial/index.md

@@ -3,7 +3,6 @@
 ````{toctree}
 ---
 maxdepth: 3
-numbered:
 ---
 
 configuration

docs/source/tutorial/xml.md

@@ -1,3 +1,84 @@
 # XML Database
 
-Coming soon!
+We will use the Rekordbox 6 database from the test data as an example:
+
+```python
+import os
+path = os.path.join(".testdata", "rekordbox 5", "database.xml")
+```
+
+An existing XML database can be parsed by passing the file path to the ``RekordboxXml``
+constructor:
+```python
+from pyrekordbox import RekordboxXml
+xml = RekordboxXml(path)
+print(xml.tostring())
+```
+
+Printing the contents results in the following output:
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<DJ_PLAYLISTS Version="1.0.0">
+    <PRODUCT Name="rekordbox" Version="6.6.2" Company="AlphaTheta"/>
+    <COLLECTION Entries="6">
+        <TRACK TrackID="253529738" Name="Demo Track 1" Artist="Loopmasters" Composer="" Album="" Grouping="" Genre="" Kind="Mp3-Datei " Size="6899624" TotalTime="172" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="128.00" DateAdded="2022-04-09" BitRate="320" SampleRate="44100" Comments="Tracks by www.loopmasters.com" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%201.mp3" Remixer="" Tonality="Fm" Label="Loopmasters" Mix="">
+            <TEMPO Inizio="0.025" Bpm="128.00" Metro="4/4" Battito="1"/>
+        </TRACK>
+        <TRACK TrackID="17109519" Name="Demo Track 2" Artist="Loopmasters" Composer="" Album="" Grouping="" Genre="" Kind="Mp3-Datei " Size="5124342" TotalTime="128" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="120.00" DateAdded="2022-04-09" BitRate="320" SampleRate="44100" Comments="Tracks by www.loopmasters.com" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Demo%20Tracks/Demo%20Track%202.mp3" Remixer="" Tonality="Fm" Label="Loopmasters" Mix="">
+            <TEMPO Inizio="0.025" Bpm="120.00" Metro="4/4" Battito="1"/>
+            <TEMPO Inizio="48.026" Bpm="120.00" Metro="4/4" Battito="1"/>
+            <TEMPO Inizio="48.525" Bpm="120.00" Metro="4/4" Battito="2"/>
+            <TEMPO Inizio="49.026" Bpm="120.00" Metro="4/4" Battito="3"/>
+            <TEMPO Inizio="49.525" Bpm="120.00" Metro="4/4" Battito="4"/>
+            <TEMPO Inizio="50.026" Bpm="120.00" Metro="4/4" Battito="1"/>
+            <TEMPO Inizio="50.525" Bpm="120.00" Metro="4/4" Battito="2"/>
+            <TEMPO Inizio="51.026" Bpm="120.00" Metro="4/4" Battito="3"/>
+            <TEMPO Inizio="51.525" Bpm="120.00" Metro="4/4" Battito="4"/>
+            <TEMPO Inizio="52.026" Bpm="120.00" Metro="4/4" Battito="1"/>
+        </TRACK>
+        <TRACK TrackID="49557014" Name="HORN" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="2010816" TotalTime="7" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/HORN.wav" Remixer="" Tonality="" Label="" Mix=""/>
+        <TRACK TrackID="209873516" Name="NOISE" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1382226" TotalTime="5" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/NOISE.wav" Remixer="" Tonality="" Label="" Mix=""/>
+        <TRACK TrackID="55231398" Name="SINEWAVE" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1515258" TotalTime="5" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/SINEWAVE.wav" Remixer="" Tonality="" Label="" Mix=""/>
+        <TRACK TrackID="92396897" Name="SIREN" Artist="" Composer="" Album="" Grouping="" Genre="" Kind="Wav-Datei " Size="1941204" TotalTime="7" DiscNumber="0" TrackNumber="0" Year="0" AverageBpm="0.00" DateAdded="2022-04-09" BitRate="2116" SampleRate="44100" Comments="" PlayCount="0" Rating="0" Location="file://localhost/C:/Music/PioneerDJ/Sampler/OSC_SAMPLER/PRESET%20ONESHOT/SIREN.wav" Remixer="" Tonality="" Label="" Mix=""/>
+    </COLLECTION>
+    <PLAYLISTS>
+        <NODE Type="0" Name="ROOT" Count="1">
+            <NODE Name="Trial playlist - Cloud Library Sync" Type="1" KeyType="0" Entries="0"/>
+        </NODE>
+    </PLAYLISTS>
+</DJ_PLAYLISTS>
+```
+
+## Tracks
+
+Individual tracks in the collection can be fetched by supplying an index
+````
+>>> xml.get_track(0)
+<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
+````
+or the `TrackID`:
+````
+>>> xml.get_track(TrackID=253529738)
+<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
+````
+
+All items in the collection can be fetched via
+````
+>>> tracks = xml.get_tracks()
+>>> tracks[0]
+<Track(Location=C:\Music\PioneerDJ\Demo Tracks\Demo Track 1.mp3)>
+````
+
+The XML attributes of a `Track` element are accessable as an attribute of the ```Track``
+object or via a dict-interface:
+````python
+>>> track = xml.get_track(0)
+>>> track.Name
+Demo Track 1
+
+>>> track["Name"]
+Demo Track 1
+````
+
+See the {ref}`XML file documentation <XML Database Format>` for a list of valid
+attributes. All XML attributes start with a capital letter.