Format and update docs

[rbdr/junction] / README.md

diff --git a/README.md b/README.md
index 44f490ddbc3ac4ed5c8cbd22e5b606718d8ba296..345fa6b8cbea553bf1d4083a78d2d6ffca8a4493 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,30 +1,85 @@
 # Junction
 
-Connect people through any URL
+Connect people through any URL.
 
-## Extension
+Junction is a web extension for Firefox, Chrome and Safari that lets you start
+an audio call at any URL.
 
-First, make sure to build the plugin. From the extension's root you can call:
+## Building
+
+Running `make` or `make package` will regenerate the content script, and
+package the extension for all browsers in the `./build/` directory with
+the following outputs:
+
+- `junction.xpi`: The firefox extension
+- `junction.zip`: The chrome extension
+- `Junction.app`: The safari extension app
+
+## Developing
+
+The project is divided into three main parts:
+
+- `server`: A server that handles message passing to establish the WebRTC
+  connections.
+- `extension`: The main code of the extension itself.
+- `safari`: The safari app, it wraps the extension using symlinks.
+
+### Dependencies
+
+- `make` to run the build commands.
+- `xcode` to build the safari extension.
+- `node` and `pnpm` to build the extension, and if you want to run the server
+  directly.
+- `podman` and `podman-compose` if you want to run the server as a container.
+- `prettier` to format Javascript, JSON, Yaml, and Markdown.
+- `xcbeautify` to format swift
+
+### Server
+
+The server is a socket.io server that relays messages between peers to help
+establish a WebRTC connection.
+
+#### Configuration
+
+You can use environment variables to control the server.
+
+- `JUNCTION_SERVER_PORT` which port to listen on. Defaults to `8000`.
+
+### Extension
+
+The extension uses WebExtension manifest v2 and is compatible with Firefox,
+Chrome and Safari.
+
+You can build all extensions using `make` in the root of the directory.
+
+If you want to run manually then you can run `pnpm install` from the
+`extension` folder to install dependencies, and `pnpm build` to generate the
+content script.
 
 ```
 $ pnpm install && pnpm build
 ```
 
-### Testing on Firefox
+#### Testing on Firefox
 
 In order to test on firefox, first go to `about:debugging`, then click
 on the `This Firefox` option. Then click on `Load Temporary Add-On` and
-point the browser to the `extension/manifest.json` file.
+point the browser to the `build/junction.xpi` file if you're using `make`, or
+`extension/manifest.json` file if you're testing without packaging.
 
-This will enable the extension and will allow you to use the inspector to debug.
+This will enable the extension and will allow you to use the inspector to
+debug.
 
-### Testing on Chrome
+#### Testing on Chrome
 
 In order to test on chrome, first go to `chrome://extensions/`. Make sure
-`Developer mode` is enabled. Then click `Load Unpacked` and point the browser
-to the `extension` directory.
+`Developer mode` is enabled. You can drag the `build/junction.zip` file or
+click `Load Unpacked` and point the browser to the `extension` directory.
+
+#### Testing on Safari
+
+Open `Junction.app` and then enable the extension in Safari.
 
-### Packaging
+### Formatting
 
-The makefile includes scripts to create a distributable package. `make package`
-should generate all supported files in the `build/` directory.
+Running `make format` will format the code with prettify and xcbeautify