[RSDK-2833] Documentation (#45)

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Generate docs
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'lib/**'
+      - 'doc/**'
+      - 'README.md'
+      - 'dartdoc_options.yaml'
+    branches: [ main ]
+
+jobs:
+  generate-docs:
+    if: github.repository_owner == 'viamrobotics'
+    runs-on: [self-hosted, x64]
+    container:
+      image: ghcr.io/cirruslabs/flutter:3.7.12
+    steps:
+      - name: Checkout Push/Workflow Dispatch
+        uses: actions/checkout@v3
+
+      - name: Setup Flutter
+        run: flutter pub get
+
+      - name: Generate docs
+        run: dart doc
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: doc/api
+          publish_branch: docs-gh_pages
+          cname: flutter.viam.dev
+
+      - name: Zip artifacts
+        run: zip html-docs.zip ./doc/api -r
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: html-docs
+          path: html-docs.zip
+

Makefile

@@ -15,6 +15,8 @@ buf: buf.yaml buf.gen.yaml
 	PATH=$(PATH_WITH_TOOLS) protoc --dart_out=grpc:lib/src/gen -I$(PROTOBUF) $(PROTOBUF)/google/protobuf/struct.proto
 	PATH=$(PATH_WITH_TOOLS) protoc --dart_out=grpc:lib/src/gen -I$(PROTOBUF) $(PROTOBUF)/google/protobuf/timestamp.proto
 	PATH=$(PATH_WITH_TOOLS) protoc --dart_out=grpc:lib/src/gen -I$(PROTOBUF) $(PROTOBUF)/google/protobuf/wrappers.proto
+	# There's a bug in dart protoc where it doesn't understand that `call` is already taken
+	sed -i '' 's/yield\* call(call, await request);/yield\* this\.call(call, await request);/g' ./lib/src/gen/proto/rpc/webrtc/v1/signaling.pbgrpc.dart
 
 setup:
 	dart pub global activate protoc_plugin

README.md

@@ -1,118 +1,59 @@
 # Viam Flutter SDK
 Build and connect to robots with Flutter
 
+![build status](https://img.shields.io/github/actions/workflow/status/viamrobotics/viam-flutter-sdk/test.yaml?branch=main)
+[![license](https://img.shields.io/badge/license-Apache_2.0-blue)](https://github.com/viamrobotics/viam-flutter-sdk/blob/main/LICENSE)
+
 ## (In)stability Notice
 
 > **Warning**
 > This is an alpha release of the Viam Flutter SDK. The only guarantee is that there **WILL** be breaking changes to the API. We will enumerate these changes in the release notes.
 
 ## Getting started
-### **auth0**
-
-Ask Viam for auth0domain, appId, audience.
-
-### **iOS**
-
-
-**ios/Podfile**
-
-
-The minimum target platform supported by the Auth0 Flutter SDK is iOS 12.0
-
-```ruby
-platform :ios, '12.0'
-```
-
-The WebRTC.xframework compiled after the m104 release no longer supports iOS arm devices, so need to add the config.build_settings
+Make sure your project meets the minimum requirements:
+* Minimum iOS target: 12.0
+* Minimum Android SDK: 23
 
-```ruby
- # snippet begin
-  if target.name == "WebRTC-SDK"
-      target.build_configurations.each do |build_configuration|
-        build_configuration.build_settings['ONLY_ACTIVE_ARCH'] = 'YES'
-       	build_configuration.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = '$(inherited) i386'
-       	build_configuration.build_settings['SWIFT_VERSION'] = '5.0'  # required by simple_permission
-        build_configuration.build_settings['ENABLE_BITCODE'] = 'NO'
+As this SDK is still in alpha, it is not yet published to [pub.dev](https://pub.dev). While we have plans to publish there soon, for now you should install the SDK directly from [GitHub](https://github.com/viamrobotics/viam-flutter-sdk):
 
-      end
-    end
- # snippet end
-```
-
-**ios/Runner/Info.plist**
-
-```plist
-  <!-- 👇 New code -->
-  <key>CFBundleURLTypes</key>
-  <array>
-    <dict>
-      <key>CFBundleTypeRole</key>
-      <string>Editor</string>
-      <key>CFBundleURLName</key>
-      <string>auth0</string>
-      <key>CFBundleURLSchemes</key>
-      <array>
-        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
-      </array>
-    </dict>
-  </array>
-  <!-- 👆 New code -->
-```
+```yaml
+# pubspec.yaml
 
-### **Android**
+...
 
-**android/app/build.gradle**
-
-```gradle
-android {
-    //...
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_1_8
-        targetCompatibility JavaVersion.VERSION_1_8
-    }
-}
+dependencies:
+  ...
+  viam_sdk:
+    url: https://github.com/viamrobotics/viam-flutter-sdk.git
+    ref: main
 ```
 
-```gradle
-android {
-    // ...
-
-    defaultConfig {
-        // ...
-        manifestPlaceholders += [auth0Domain: "<YOUR_AUTH0_DOMAIN>", auth0Scheme: "<SCHEME>"] // 👈 New code
-    }
+Don't forget to run `flutter pub get` after updating your `pubspec.yaml`
 
-    // ...
-}
-```
-
-If necessary, in the same build.gradle you will need to increase minSdkVersion of defaultConfig up to 23 (currently default Flutter generator set it to 16).
 
 ## Usage
-
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder.
+You can use the Viam SDK to connect to an existing robot (to create a robot, view the [documentation](https://docs.viam.com/) or [try Viam](https://docs.viam.com/try-viam/)).
 
 ```dart
 import 'package:viam_sdk/viam_sdk.dart';
 
-final viam = Viam.instance();
+// Connect to an existing robot
+// *NOTE* Get the <LOCATION> and <SECRET> from app.viam.com
+final options = RobotClientOptions.withLocationSecret('<SECRET>');
+final robot = await RobotClient.atAddress('<LOCATION>', options);
 
-await viam.connect(
-        url: '<ROBOT_URL>',
-        payload: '<ROBOT_SECRET>',
-        accessToken: '<TOKEN>',
-        disableWebRtc: false,
-        port: 443,
-        secure: true,
-        );
-
- final resourceNames = await viam.viamResourceService.getResourceNames();
+// Print the available resources
+print(robot.resourceNames);
 
+// Access a component
+final movementSensor = MovementSensor.fromRobot(robot, 'my_sensor');
+print(await movementSensor.readings())
 ```
 
-## Additional information
+## Example app
+View the sample app in the [`/example`](https://github.com/viamrobotics/viam-flutter-sdk/blob/main/example/) directory to see a more in-depth example.
+
+## License
+Copyright 2021-2023 Viam Inc.
 
-TODO: Tell users more about the package: where to find more information, how to
-contribute to the package, how to file issues, what response they can expect
-from the package authors, and more.
+Apache 2.0 - See [LICENSE](https://github.com/viamrobotics/viam-python-sdk/blob/main/LICENSE) file

dartdoc_options.yaml

@@ -0,0 +1,7 @@
+dartdoc:
+  categories:
+    "Protobuf Definitions":
+      markdown: doc/Protobuf.md
+      name: Protobuf Definitions
+  categoryOrder: ["Protobuf Definitions"]
+  nodoc: ['**/di/**', '**/domain/**']

doc/Protobuf.md

@@ -0,0 +1,3 @@
+# Viam protobuf definitions
+
+Viam uses [protocol buffers](https://protobuf.dev/) for (de)serialization. While native implementations for many of these protobufs exist in the SDK, there can be some instances where direct access to protobuf messages is required. The definitions of all protobufs provided by Viam are listed below.

lib/protos/app/app.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for app
+/// {@category Protobuf Definitions}
+library viam_protos.app.app;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/v1/app.pbenum.dart';
+export '../../../src/gen/app/v1/app.pbjson.dart';
+export '../../../src/gen/app/v1/app.pb.dart';
+export '../../../src/gen/app/v1/app.pbgrpc.dart';

lib/protos/app/billing.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for billing
+/// {@category Protobuf Definitions}
+library viam_protos.app.billing;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/v1/billing.pbenum.dart';
+export '../../../src/gen/app/v1/billing.pbjson.dart';
+export '../../../src/gen/app/v1/billing.pbgrpc.dart';
+export '../../../src/gen/app/v1/billing.pb.dart';

lib/protos/app/data.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for data
+/// {@category Protobuf Definitions}
+library viam_protos.app.data;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/data/v1/data.pbenum.dart';
+export '../../../src/gen/app/data/v1/data.pb.dart';
+export '../../../src/gen/app/data/v1/data.pbjson.dart';
+export '../../../src/gen/app/data/v1/data.pbgrpc.dart';

lib/protos/app/data_sync.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for data_sync
+/// {@category Protobuf Definitions}
+library viam_protos.app.data_sync;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/datasync/v1/data_sync.pbenum.dart';
+export '../../../src/gen/app/datasync/v1/data_sync.pbgrpc.dart';
+export '../../../src/gen/app/datasync/v1/data_sync.pbjson.dart';
+export '../../../src/gen/app/datasync/v1/data_sync.pb.dart';

lib/protos/app/ml_training.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for ml_training
+/// {@category Protobuf Definitions}
+library viam_protos.app.ml_training;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/mltraining/v1/ml_training.pbenum.dart';
+export '../../../src/gen/app/mltraining/v1/ml_training.pbgrpc.dart';
+export '../../../src/gen/app/mltraining/v1/ml_training.pb.dart';
+export '../../../src/gen/app/mltraining/v1/ml_training.pbjson.dart';

lib/protos/app/model.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for model
+/// {@category Protobuf Definitions}
+library viam_protos.app.model;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/model/v1/model.pbenum.dart';
+export '../../../src/gen/app/model/v1/model.pbjson.dart';
+export '../../../src/gen/app/model/v1/model.pb.dart';
+export '../../../src/gen/app/model/v1/model.pbgrpc.dart';

lib/protos/app/packages.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for packages
+/// {@category Protobuf Definitions}
+library viam_protos.app.packages;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/packages/v1/packages.pbjson.dart';
+export '../../../src/gen/app/packages/v1/packages.pb.dart';
+export '../../../src/gen/app/packages/v1/packages.pbgrpc.dart';
+export '../../../src/gen/app/packages/v1/packages.pbenum.dart';

lib/protos/app/robot.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for robot
+/// {@category Protobuf Definitions}
+library viam_protos.app.robot;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/app/v1/robot.pb.dart';
+export '../../../src/gen/app/v1/robot.pbjson.dart';
+export '../../../src/gen/app/v1/robot.pbgrpc.dart';
+export '../../../src/gen/app/v1/robot.pbenum.dart';

lib/protos/common/common.dart

@@ -0,0 +1,9 @@
+/// The proto definitions for common
+/// {@category Protobuf Definitions}
+library viam_protos.common.common;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/common/v1/common.pbenum.dart';
+export '../../../src/gen/common/v1/common.pb.dart';
+export '../../../src/gen/common/v1/common.pbjson.dart';

lib/protos/component/arm.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for arm
+/// {@category Protobuf Definitions}
+library viam_protos.component.arm;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/arm/v1/arm.pb.dart';
+export '../../../src/gen/component/arm/v1/arm.pbenum.dart';
+export '../../../src/gen/component/arm/v1/arm.pbjson.dart';
+export '../../../src/gen/component/arm/v1/arm.pbgrpc.dart';

lib/protos/component/audioinput.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for audioinput
+/// {@category Protobuf Definitions}
+library viam_protos.component.audioinput;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/audioinput/v1/audioinput.pbenum.dart';
+export '../../../src/gen/component/audioinput/v1/audioinput.pbjson.dart';
+export '../../../src/gen/component/audioinput/v1/audioinput.pb.dart';
+export '../../../src/gen/component/audioinput/v1/audioinput.pbgrpc.dart';

lib/protos/component/base.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for base
+/// {@category Protobuf Definitions}
+library viam_protos.component.base;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/base/v1/base.pbjson.dart';
+export '../../../src/gen/component/base/v1/base.pbgrpc.dart';
+export '../../../src/gen/component/base/v1/base.pbenum.dart';
+export '../../../src/gen/component/base/v1/base.pb.dart';

lib/protos/component/board.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for board
+/// {@category Protobuf Definitions}
+library viam_protos.component.board;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/board/v1/board.pbgrpc.dart';
+export '../../../src/gen/component/board/v1/board.pbjson.dart';
+export '../../../src/gen/component/board/v1/board.pbenum.dart';
+export '../../../src/gen/component/board/v1/board.pb.dart';

lib/protos/component/camera.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for camera
+/// {@category Protobuf Definitions}
+library viam_protos.component.camera;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/camera/v1/camera.pbenum.dart';
+export '../../../src/gen/component/camera/v1/camera.pb.dart';
+export '../../../src/gen/component/camera/v1/camera.pbjson.dart';
+export '../../../src/gen/component/camera/v1/camera.pbgrpc.dart';

lib/protos/component/encoder.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for encoder
+/// {@category Protobuf Definitions}
+library viam_protos.component.encoder;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/encoder/v1/encoder.pbjson.dart';
+export '../../../src/gen/component/encoder/v1/encoder.pbgrpc.dart';
+export '../../../src/gen/component/encoder/v1/encoder.pb.dart';
+export '../../../src/gen/component/encoder/v1/encoder.pbenum.dart';

lib/protos/component/gantry.dart

@@ -0,0 +1,10 @@
+/// The proto definitions for gantry
+/// {@category Protobuf Definitions}
+library viam_protos.component.gantry;
+
+// THIS FILE IS AUTOMATICALLY GENERATED
+// DO NOT OVERWRITE
+export '../../../src/gen/component/gantry/v1/gantry.pbjson.dart';
+export '../../../src/gen/component/gantry/v1/gantry.pbgrpc.dart';
+export '../../../src/gen/component/gantry/v1/gantry.pb.dart';
+export '../../../src/gen/component/gantry/v1/gantry.pbenum.dart';