Reorganise readme and docs

.jazzy.yaml

@@ -2,15 +2,30 @@ module: HAP
 author: Bouke Haarsma
 author_url: https://boukehaarsma.nl
 theme: fullwidth
-clean: true
+output: .docs
+clean: yes
 github_url: https://github.com/Bouke/HAP
 github_file_prefix: https://github.com/Bouke/HAP/tree/master
 dash_url: http://boukehaarsma.nl/HAP/HAP.xml
+documentation: docs/*.md
+abstract: docs/api/*.md
+swift_build_tool: spm
+hide_documentation_coverage: yes
+hide_unlisted_documentation: yes
 custom_categories:
+  - name: Documentation
+    children:
+      - Getting Started
+      - Usage
+      - Create an Accessory
+      - Design
+      - Development
   - name: Server
     children:
       - Device
       - DeviceDelegate
+      - PairingState
+      - PairingStateError
       - Server
       - QRCode
   - name: Accessory
@@ -30,6 +45,7 @@ custom_categories:
       - CharacteristicType
       - CharacteristicUnit
       - CharacteristicValueType
+      - PredefinedCharacteristic
   - name: Characteristic Enums
     children:
       - Enums

README.md

@@ -23,126 +23,13 @@ Remember that this is not a commercial product, but the result of free labor.
 - If you found a bug, open an issue here on GitHub. The more detail the better!
 - If you want to contribute, submit a pull request.
 
-## Getting Started
+## Contents
 
-### MacOS
-
-Install libsodium (used for Curve25519 and Ed25519):
-
-    brew install libsodium
-
-And then build and run the project itself, specifying a release build for good performance:
-
-    swift run -c release hap-server
-
-### Linux
-
-Install dependencies:
-
-    sudo apt install openssl libssl-dev libsodium-dev libcurl4-openssl-dev libavahi-compat-libdnssd-dev
-
-Make sure you have libsodium 1.0.9 or above. Ubuntu 16.10 or later suffices. Otherwise you have to compile and install libsodium from source:
-
-    wget https://download.libsodium.org/libsodium/releases/libsodium-1.0.12.tar.gz
-    tar xzf libsodium-1.0.12.tar.gz
-    cd libsodium-1.0.12
-    ./configure
-    make && make check
-    sudo make install
-    sudo ldconfig
-
-And then build the project itself, specifying a release build for good performance:
-
-    swift run -c release hap-server
-
-## Raspberry Pi (Raspbian Stretch)
-
-There are currently no official binaries from swift.org targetting ARM / Raspbian, however there's an active community working on Swift on ARM. You can [install binaries from their repository][1]:
-
-    curl -s https://packagecloud.io/install/repositories/swift-arm/release/script.deb.sh | sudo bash
-    sudo apt install swift5
-
-## Usage
-
-Modify `Sources/hap-server/main.swift` to include your own accessories, or import the _HAP_ library into your own project.
-
-On Mac OS, you can debug using XCode by running the command `swift package generate-xcodeproj` and the opening the resulting `HAP.xcodeproj` project. Select and run the `hap-server` target.
-
-## Extensibility
-
-The following code snippet how you would model a fictious accessory
-representing a mobile power bank.
-
-```swift
-class PowerBankAccessory: Accessory {
-    let service = PowerBankService()
-    init(info: Service.Info) {
-        super.init(info: info, type: .outlet, services: [service])
-    }
-}
-class PowerBankService: Service {
-    public let on = GenericCharacteristic<Bool>(
-        type: .on,
-        value: false)
-    public let inUse = GenericCharacteristic<Bool>(
-        type: .outletInUse,
-        value: true,
-        permissions: [.read, .events])
-    public let batteryLevel = GenericCharacteristic<Double>(
-        type: .batteryLevel,
-        value: 100,
-        permissions: [.read, .events])
-
-    init() {
-        super.init(type: .outlet, characteristics: [
-            AnyCharacteristic(on),
-            AnyCharacteristic(inUse),
-            AnyCharacteristic(batteryLevel)
-        ])
-    }
-}
-```
-
-- See also: [My Home](https://github.com/Bouke/My-Home/tree/master/Sources)
-
-## Object-Oriented Design
-
-A high-level overview of the objects involved are shown in the diagram below.
-The terminology of HAP (Device, Accessory, Service, Characteristic) is
-followed for ease of understanding.
-
-                          +------------+
-                          | NetService |
-                          +------------+
-                                 |
-                                 | delegate
-                                 v
-       +--------+ 1     0…1 +--------+ *   * +---------------------+
-       | Device |-----------| Server |-------| Controller (iPhone) |
-       +--------+           +--------+       +---------------------+
-            | 1                           * /
-            | *                           /
-      +-----------+                     /
-      | Accessory |                   /
-      +-----------+                 /
-            | 1                   / > read, events
-            | *                 / < write, subscribe
-       +---------+            /
-       | Service |          /
-       +---------+        /
-            | 1         /
-            | *     * /
-    +----------------+
-    | Characteristic |
-    +----------------+
-
-## Development
-
-### Running tests
-
-Certain tests involve crypto, which can be a bit slow in debug builds. Best to run the tests with a release build, like this:
-
-    swift test -c release -Xswiftc -enable-testing
+- [Getting Started](https://boukehaarsma.nl/HAP/getting-started.html)
+- [Usage](https://boukehaarsma.nl/HAP/usage.html)
+- [Create an Accessory](https://boukehaarsma.nl/HAP/create-an-accessory.html)
+- [Design](https://boukehaarsma.nl/HAP/design.html)
+- [Development](https://boukehaarsma.nl/HAP/development.html)
 
 ## Credits
 

docs/Create an Accessory.md

@@ -0,0 +1,35 @@
+Create an Accessory
+===================
+
+The following code snippet how you would model a fictious accessory
+representing a mobile power bank.
+
+```swift
+class PowerBankAccessory: Accessory {
+    let service = PowerBankService()
+    init(info: Service.Info) {
+        super.init(info: info, type: .outlet, services: [service])
+    }
+}
+class PowerBankService: Service {
+    public let on = GenericCharacteristic<Bool>(
+        type: .on,
+        value: false)
+    public let inUse = GenericCharacteristic<Bool>(
+        type: .outletInUse,
+        value: true,
+        permissions: [.read, .events])
+    public let batteryLevel = GenericCharacteristic<Double>(
+        type: .batteryLevel,
+        value: 100,
+        permissions: [.read, .events])
+
+    init() {
+        super.init(type: .outlet, characteristics: [
+            AnyCharacteristic(on),
+            AnyCharacteristic(inUse),
+            AnyCharacteristic(batteryLevel)
+        ])
+    }
+}
+```

docs/Design.md

@@ -0,0 +1,35 @@
+Design
+======
+
+## Object-Oriented Design
+
+A high-level overview of the objects involved are shown in the diagram below.
+The terminology of HAP (Device, Accessory, Service, Characteristic) is
+followed for ease of understanding.
+
+```
+                      +------------+
+                      | NetService |
+                      +------------+
+                             |
+                             | delegate
+                             v
+   +--------+ 1     0…1 +--------+ *   * +---------------------+
+   | Device |-----------| Server |-------| Controller (iPhone) |
+   +--------+           +--------+       +---------------------+
+        | 1                           * /
+        | *                           /
+  +-----------+                     /
+  | Accessory |                   /
+  +-----------+                 /
+        | 1                   / > read, events
+        | *                 / < write, subscribe
+   +---------+            /
+   | Service |          /
+   +---------+        /
+        | 1         /
+        | *     * /
++----------------+
+| Characteristic |
++----------------+
+```

docs/Development.md

@@ -0,0 +1,10 @@
+Development
+===========
+
+## Running tests
+
+Certain tests involve crypto, which can be a bit slow in debug builds. Best to run the tests with a release build, like this:
+
+```
+swift test -c release -Xswiftc -enable-testing
+```

docs/Getting Started.md

@@ -0,0 +1,41 @@
+Getting Started
+===============
+
+## Installing dependencies
+
+### macOS
+On macOS this package depends on libsodium to provide certain crypto algorithms. Install it using homebrew:
+```
+brew install libsodium
+```
+
+### Linux
+On Debian based Linux distributions you need a few packages. Install them using apt:
+```
+sudo apt install openssl libssl-dev libsodium-dev libcurl4-openssl-dev libavahi-compat-libdnssd-dev
+```
+
+If your package manager doesn't provide libsodium 1.0.9 or higher, install it from source:
+```
+wget https://download.libsodium.org/libsodium/releases/libsodium-1.0.12.tar.gz
+tar xzf libsodium-1.0.12.tar.gz
+cd libsodium-1.0.12
+./configure
+make && make check
+sudo make install
+sudo ldconfig
+```
+
+### Linux ARM / Raspberry Pi (Raspbian Stretch)
+There are currently no official binaries from swift.org targetting ARM / Raspbian, however there's an active community working on Swift on ARM. You can [install binaries from their repository][1]:
+
+```
+curl -s https://packagecloud.io/install/repositories/swift-arm/release/script.deb.sh | sudo bash
+sudo apt install swift5
+```
+
+## First run
+Now that you have all the dependencies installed, you should be able to build and run the project. For optimal performance, use a release build:
+```
+swift run -c release hap-server
+```

docs/Usage.md

@@ -0,0 +1,8 @@
+Usage
+=====
+
+Modify `Sources/hap-server/main.swift` to include your own accessories, or import the _HAP_ library into your own project.
+
+On Mac OS, you can debug using XCode by running the command `swift package generate-xcodeproj` and the opening the resulting `HAP.xcodeproj` project. Select and run the `hap-server` target.
+
+- See also: [My Home](https://github.com/Bouke/My-Home/tree/master/Sources)

docs/api/Server.md

@@ -0,0 +1 @@
+Use the `Device` instance to manage the setup code, accessories and controller pairings. You can assign a delegate to be notified of certain events. The `Server` manages IP connectivity and network discovery advertisements.