Merge pull request #2 from FelixNgFender/main

docs(server): new docs site for ARFlow server

.flake8

@@ -6,3 +6,9 @@ extend-ignore:
   E231,
   # line too long (conflicts with Black)
   E501,
+
+; exclude:
+;   # gRPC-generated files
+;   ./python/arflow/service_pb2_grpc.py,
+;   ./python/arflow/service_pb2.py,
+;   ./python/arflow/service_pb2.pyi,

.github/workflows/website.yml

@@ -0,0 +1,83 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches:
+      - main
+    paths:
+      - 'python/**'
+      - '.github/workflows/website.yml'
+      - 'website/**'
+
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10.12'
+
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: '1.8.3'
+
+      - name: Setup a local virtual environment (if no poetry.toml file)
+        working-directory: ./python
+        run: |
+          poetry config virtualenvs.create true --local
+          poetry config virtualenvs.in-project true --local
+
+      - name: Define a cache for the virtual environment based on the dependencies lock file
+        uses: actions/cache@v3
+        with:
+          path: ./python/.venv
+          key: venv-${{ hashFiles('./python/poetry.lock') }}
+
+      - name: Install docs dependencies
+        working-directory: ./python
+        run: poetry install --with docs
+
+      - name: Build the documentation
+        working-directory: ./python
+        run: poetry run make-docs
+
+      - name: Move docs to website directory
+        run: |
+          mkdir -p ./website/docs/server/
+          cp -r ./python/docs/* ./website/docs/server/
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./website
+
+  # Single deploy job since we're just deploying
+  deploy:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -299,3 +299,5 @@ crashlytics-build.properties
 .ionide
 
 # End of https://www.toptal.com/developers/gitignore/api/macos,visualstudiocode,python,unity
+
+website/docs/*

.vscode/settings.json

@@ -24,4 +24,8 @@
         "thecakelab",
         "Xihe"
     ],
+    "conventionalCommits.scopes": [
+        "server",
+        "client"
+    ],
 }

protos/arflow/service.proto

@@ -2,8 +2,12 @@ syntax = "proto3";
 
 option csharp_namespace = "ARFlow";
 
+// The ARFlowService service definition.
 service ARFlowService {
+    // Registers a device with the given specifications.
     rpc register(RegisterRequest) returns (RegisterResponse);
+
+    // Sends a data frame from a device.
     rpc data_frame(DataFrameRequest) returns (DataFrameResponse);
 }
 
@@ -55,7 +59,7 @@ message RegisterRequest {
 }
 
 message RegisterResponse {
-    string message = 1;
+    string uid = 1;
 }
 
 message DataFrameRequest {

python/.gitignore

@@ -254,3 +254,9 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/macos,windows,visualstudiocode,python
 
 test_data/*
+docs/*
+
+# Ignore all gRPC-generated files
+# arflow/service_pb2_grpc.py
+# arflow/service_pb2.py
+# arflow/service_pb2.pyi

python/README.md

@@ -26,3 +26,43 @@ def main():
 if __name__ == "__main__":
     main()
 ```
+
+## Development
+
+### Important Packages & Tools
+
+#### [`poetry`](https://python-poetry.org)
+
+Python dependency management. 
+
+ARFlow uses `poetry` to manage dependencies and run commands. Commands can be found in the `pyproject.toml` file in the `[tool.poetry.scripts]` section and can be run via `poetry run <command>`.
+
+#### [`protobuf`](https://protobuf.dev)
+
+A language-neutral, platform-neutral, extensible mechanism for serializing structured data.
+
+ARFlow uses `protobuf` to define the communication protocol between the server and the client. The protocol is defined in [`service.proto`](../protos/arflow/service.proto) and can be compiled using [`compile.sh`](../protos/scripts/compile.sh).
+
+#### [`pickle`](https://docs.python.org/3/library/pickle.html)
+
+Implements binary protocols for serializing and deserializing Python objects. Pickling is the same as serialization, marshalling, or flattening in other languages. The inverse operation is called unpickling.
+
+#### [`asyncio`](https://docs.python.org/3/library/asyncio.html)
+
+A library to write **concurrent** code using using the `async` and `await` syntax. Perfect for writing IO-bound and high-level structured network code.
+
+#### [`rerun.io`](https://github.com/rerun-io/rerun)
+
+A tool to build time aware visualizations of multimodal data. 
+
+ARFlow uses the Rerun Python SDK to visualize the data collected by the ARFlow server.
+
+### Documentation
+
+ARFlow uses [`pdoc`](https://pdoc.dev). You can refer to their documentation for more information on how to generate documentation. If you create a new submodule, make sure to add it to the `__all__` list defined in the `_init__.py` file of the `arflow` package.
+
+To preview the documentation locally, run:
+
+```bash
+poetry run pdoc <module_name>
+```

python/arflow/__init__.py

@@ -1,3 +1,15 @@
+"""
+.. include:: ../README.md
+"""
+
+from arflow.core import *  # noqa
 from arflow.replay import *  # noqa
 from arflow.serve import *  # noqa
 from arflow.service_pb2 import *  # noqa
+
+# https://pdoc.dev/docs/pdoc.html#exclude-submodules-from-being-documented
+__all__ = [  # noqa
+    "core",  # noqa
+    "replay",  # noqa
+    "serve",  # noqa
+]