Better documentation

docs/conf.py

@@ -14,17 +14,25 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.duration", "autoapi.extension"]
+extensions = [
+    "myst_parser",
+    "sphinx.ext.duration",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "autoapi.extension"
+]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- AutoAPI Options ---------------------------------------------------------
 autoapi_dirs = ["../findmy/"]
+autoapi_add_toctree_entry = False
 autoapi_options = [
     "members",
     "undoc-members",
     "show-inheritance",
+    "show-inheritance-diagram",
     "show-module-summary",
     "special-members",
     "imported-members",
@@ -33,5 +41,5 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
+html_theme = "furo"
 html_static_path = ["_static"]

docs/getstarted/1-account.md

@@ -0,0 +1,7 @@
+# Logging in
+
+Some useful features of this library require an active login session with Apple in order to work correctly.
+The reason for this is that the remote endpoints require authentication to actually retrieve data.
+This page will guide you through the steps needed to log into an Apple account using FindMy.py.
+
+

docs/getstarted/index.md

@@ -0,0 +1,10 @@
+# Getting Started
+
+* * *
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```

docs/index.md

@@ -0,0 +1,33 @@
+# FindMy.py
+
+= 🍏 + 🎯 + 🐍!
+
+FindMy.py is a Python library aiming to provide everything you need
+to interact with **Apple's FindMy Network**.
+Its primary aims are feature completeness, reliability and elegant API design.
+It abstracts all the heavy lifting away, while keeping the control flow in your hands.
+
+## Jump To
+
+[//]: # (This is hidden to prevent it from showing on the home page)
+```{toctree}
+:hidden:
+
+Home <self>
+```
+
+[//]: # (Documentation can be expanded to maxdepth 2)
+```{toctree}
+:maxdepth: 2
+
+getstarted/index
+technical/index
+```
+
+[//]: # (Show these with a maxdepth of 1)
+```{toctree}
+:maxdepth: 1
+
+API Reference <autoapi/findmy/index>
+genindex
+```

docs/technical/1-Network.md

@@ -0,0 +1,41 @@
+# The Network
+
+This page aims to provide an overview of how the Find My-network works on a technical level.
+It does this by explaining in detail what data the tags are broadcasting, how this is picked up
+by surrounding iDevices, and how generated location reports can be retrieved.
+
+```{note}
+While official AirTags (and compatible 3rd party tags) use the same principles as described
+in this document, they also offer a key rotation feature. To learn more about
+how this works, please check out the dedicated [AirTags](#10-AirTags) page.
+```
+
+## Overview
+
+Simply said, the FindMy-network works by having accessories such as AirTags broadcast a unique signal over bluetooth.
+Any nearby iDevice, such as iPhones or iPads, are able to receive this signal. Once the device is aware of the nearby
+accessory, it will upload its current location to Apple's servers, from where it can be retrieved by the owner of the accessory.
+
+Apple has put a lot of effort into making the network as private as possible. By utilizing encryption,
+it is possible for finder devices to encrypt their location with a key that the accessory is broadcasting
+before sending it to Apple. This public key allows encryption of certain data, but not decryption. In order
+to download location reports for the accessory, we therefore need the private key corresponding to said public key.
+These keys, together called a key pair, were generated and exchanged when the accessory was first paired and are now
+stored on the owner's devices. By downloading the correct encrypted location reports and then locally decrypting
+said reports using the private key, users are able to track their devices without Apple ever being able to read the location.
+
+![](https://github.com/seemoo-lab/openhaystack/raw/main/Resources/FindMyOverview.png)
+
+*An overview of the FindMy-network. Source: [SEEMOO-LAB](https://www.petsymposium.org/2021/files/papers/issue3/popets-2021-0045.pdf)*.
+
+Fetching (encrypted) location reports still requires an Apple account. It is worth noting however, that anyone can download
+anyone else's location reports for any of their devices; however, due to the encryption scheme discussed above,
+doing this would be rather useless as none of the retrieved reports could be decrypted. This scheme allows devices
+to operate without being linked to a specific Apple account. The below dependency diagram visually explains how this entire
+system hinges on the availability of the private key; without it, location reports could not be retrieved and decrypted.
+
+
+![](dependency_diagram.png)
+
+*A dependency diagram of data in the network. An arrow pointing from A to B means that in order
+to retrieve B, we first require A.*

docs/technical/index.md

@@ -0,0 +1,17 @@
+# Technical Documentation
+
+This category serves as a place to provide technical documentation about the Find My network.
+More specifically, it serves as a technical reference for how certain features in this
+library have been implemented.
+
+Most of the knowledge in this section has been sourced from other genius minds.
+Make sure to check out the references section on the specific pages to read more about the topics.
+
+* * *
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```

pyproject.toml

@@ -37,6 +37,8 @@ optional = true
 [tool.poetry.group.docs.dependencies]
 sphinx = "^7.2.6"
 sphinx-autoapi = "3.3.1"
+furo = "^2024.1.29"
+myst-parser = "^2.0.0"
 
 [tool.pyright]
 venvPath = "."