docs: updates for v0.2.0

docs/advanced-usage/_category_.json → docs/composing/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Advanced Usage",
-  "position": 5,
+  "label": "Composing",
+  "position": 3,
   "link": {
     "type": "generated-index",
     "description": "Learn more advanced techniques to use protoconf."

docs/advanced-usage/code-reuse.mdx → docs/composing/code-reuse.mdx

@@ -10,9 +10,7 @@ In addition to defining helper functions within a single starlark file, protocon
 
 Here is an example:
 
-`./src/myproject/helpers.pinc`:
-
-```python
+```python title="src/myproject/helpers.pinc" showLineNumbers
 load("//myproject/v1/server_config.proto", "ServerConfiguration")
 
 # A global variable
@@ -28,9 +26,7 @@ def create_default_config():
     )
 ```
 
-`./src/myproject/server_config.pconf`:
-
-```python
+```python title="src/myproject/server_config.pconf" showLineNumbers
 load("//myproject/helpers.pinc", "create_default_config", "default_request_timeout")
 
 def main():

docs/advanced-usage/multiple-outputs.mdx → docs/composing/multiple-outputs.mdx

@@ -9,7 +9,7 @@ protoconf allows for the generation of multiple config outputs from a single Sta
 
 To use this feature, you should use the `.mpconf` extension for your Starlark file. Then, you can return a dictionary from your `main` function, where each key-value pair represents a different configuration output. Here's an example:
 
-```python title=./src/myproject/server_config.mpconf
+```python title="src/myproject/server_config.mpconf" showLineNumbers
 load("//myproject/v1/server_config.proto", "ServerConfiguration")
 load("//myproject/helpers.pinc", "create_default_config")
 

docs/composing/mutation-service/reflection.mdx

@@ -0,0 +1,40 @@
+---
+sidebar_position: 4
+---
+
+# Reflection (UI)
+
+:::info
+This feature available since `v0.2.0`
+:::
+
+The protoconf server supports gRPC reflection to auto-generate UI for configurations. To allow reflection for your config struct, simply define a `service` containing a `rpc` method definition with your config struct as the input message `protoconf.v1.ConfigMutationResponse` as the result message.
+
+```protobuf title="src/myproject/server_config.proto" showLineNumbers
+syntax = "proto3";
+
+import "google/protobuf/duration.proto";
+// highlight-next-line
+import "protoconf/v1/protoconf.proto";
+
+package myproject.v1;
+
+message ServerConfiguration {
+  bool is_debug = 1;
+  uint32 max_connections = 2;
+  float max_payload_size_mb = 3;
+  google.protobuf.Duration request_timeout = 4;
+}
+
+// highlight-start
+service ServerConfigurationService {
+  rpc Set(ServerConfiguration) returns (protoconf.v1.ConfigMutationResponse);
+}
+// highlight-end
+```
+
+Then run the protoconf server (`protoconf serve .`) or (`protoconf devserver .`) and go to http://localhost:4300.
+
+Use the request `metadata` to define the mutation `path`.
+
+![Protoconf UI](/img/grpc-ui.png)

docs/advanced-usage/pipelining.mdx → docs/composing/pipelining.mdx

@@ -9,7 +9,7 @@ In more advanced scenarios, you may want to implement a pipeline for config mani
 
 The following is an example of how you can implement config manipulation pipelining in protoconf:
 
-```python title=./src/myproject/helpers.pinc
+```python title="src/myproject/helpers.pinc" showLineNumbers
 load("//myproject/v1/server_config.proto", "ServerConfiguration")
 
 def Chain(msg, *hooks):
@@ -38,7 +38,7 @@ api = struct(
 )
 ```
 
-```python title=./src/myproject/server_config.pconf
+```python title="rc/myproject/server_config.pconf" showLineNumbers
 load("//myproject/helpers.pinc", "api")
 
 def main():

docs/consuming/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Consuming",
+  "position": 5
+}

docs/delivering/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Delivering",
+  "position": 4
+}

docs/consume-config-updates.mdx → docs/getting-started/consume-config-updates.mdx

@@ -13,21 +13,19 @@ protoconf provides a gRPC service that allows your application to subscribe to c
 
 This guide will walk you through how to subscribe to configuration updates using the protoconf agent in various languages: Go, Python, Node.js, Rust, and Java.
 
-## protoconf Agent
+## protoconf Dev server
 
-To start the protoconf agent in development mode, use the following command:
+To start protoconf in development mode, use the following command:
 
 ```bash
-protoconf agent -dev .
+protoconf devserver .
 ```
 
-The protoconf agent implements the following gRPC service:
+The protoconf agent implements the following gRPC service ([See full proto file](https://github.com/protoconf/protoconf/blob/main/pb/protoconf/v1/protoconf.proto#L66)):
 
 ```protobuf
 syntax = "proto3";
-package v1;
-
-option java_package = "com.protoconf.agent.api.v1";
+package protoconf.v1;
 
 import "google/protobuf/any.proto";
 
@@ -81,7 +79,7 @@ With the above configurations, run `buf generate` to generate the code for your
 
 In Go, use the grpc package to create a client and subscribe to configuration updates:
 
-```go
+```go showLineNumbers
 package main
 
 import (
@@ -91,7 +89,7 @@ import (
     "google.golang.org/grpc"
     "google.golang.org/grpc/credentials/insecure"
     "github.com/golang/protobuf/ptypes"
-    pb "gen/go/protoconf/v1"
+    protoconfpb "github.com/protoconf/protoconf/pb/protoconf/v1"
     mypb "gen/go/myproject/v1"
 )
 
@@ -102,9 +100,9 @@ func main() {
     }
     defer conn.Close()
 
-    client := pb.NewProtoconfServiceClient(conn)
+    client := protoconfpb.NewProtoconfServiceClient(conn)
 
-    stream, err := client.SubscribeForConfig(context.Background(), &pb.ConfigSubscriptionRequest{
+    stream, err := client.SubscribeForConfig(context.Background(), &protoconfpb.ConfigSubscriptionRequest{
         Path: "myproject/server_config",
     })
     if err != nil {
@@ -118,7 +116,7 @@ func main() {
         }
 
         var config mypb.ServerConfiguration
-        if err := ptypes.UnmarshalAny(configUpdate.Value, &config); err != nil {
+        if err := configUpdate.Value.UnmarshalTo(&config); err != nil {
             log.Fatalf("Failed to unmarshal config update: %v", err)
         }
 

docs/getting-started.mdx → docs/getting-started/getting-started.mdx

@@ -22,7 +22,7 @@ For other platforms, download the latest release from the [protoconf GitHub repo
 
 First, you'll need to define your configuration structure using Protobuf. The Protobuf files should be stored under `./src/<projectname>/<version>/<filename>.proto`. For example:
 
-```protobuf title=./src/myproject/v1/server_config.proto
+```protobuf title="src/myproject/v1/server_config.proto" showLineNumbers
 syntax = "proto3";
 
 package myproject.v1;
@@ -41,7 +41,7 @@ In this example, `ServerConfiguration` is the configuration structure for a serv
 
 Next, you'll write the configuration logic in a Starlark file, which should use the `.pconf` extension and be stored under `./src/`. For example:
 
-```python title=./src/myproject/server_config.pconf
+```python title="src/myproject/server_config.pconf" showLineNumbers
 load("//myproject/v1/server_config.proto", "ServerConfiguration")
 load("//google/protobuf/duration.proto", "Duration")
 

docs/production/production-architecture.mdx → docs/getting-started/production-architecture.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 4
 ---
 
 # Production Architecture

docs/validation.mdx → docs/getting-started/validation.mdx

@@ -6,15 +6,39 @@ sidebar_position: 3
 
 # Configuration Validation
 
-protoconf provides a way to add validation rules to your configuration. These rules allow you to ensure that the configuration values meet certain criteria before they are used by your application. Validation rules are written in separate Starlark files with the `-validator` suffix, and they are associated with your configuration using the `add_validator` function.
+Protoconf provides a way to add validation rules to your configuration. These rules allow you to ensure that the configuration values meet certain criteria before they are used by your application. There are two ways to add validation rules: using annotations in your `.proto` files, or writing separate Starlark validation files.
 
-## Writing a Validation Rule
+## Using Annotations for Validation
+
+You can add validation rules directly to your `.proto` files using the `validate/validate.proto` and `buf/validate/validate.proto` annotations. These annotations allow you to specify constraints on your message fields.
+
+First, import the `validate.proto` file in your `.proto` file:
+
+```protobuf
+import "validate/validate.proto";
+```
+
+Then, you can add validation rules to your message fields using the `validate.rules` option:
+
+```protobuf
+message ServerConfiguration {
+    int32 max_connections = 1 [(validate.rules).int32.gt = 0];
+    double max_payload_size_mb = 2 [(validate.rules).double = {gt: 0.1, lt: 100.0}];
+    int32 request_timeout = 3 [(validate.rules).int32.gt = 0];
+}
+```
+
+These annotations will be checked when the message is deserialized, and if any of the constraints are not met, an error will be thrown. This allows you to catch invalid configurations early, before they cause problems in your application.
+
+## Writing a Validation Rule with Starlark (Advanced)
+
+For more complex validation rules, you can write separate Starlark files with the `-validator` suffix. These files are associated with your configuration using the `add_validator` function.
 
 Create a new Starlark file with the `-validator` suffix. For example, for a configuration defined in `./src/myproject/v1/server_config.proto`, the validation file would be `./src/myproject/v1/server_config.proto-validator`.
 
 In this file, load the configuration message, define a validation function, and then add the validator:
 
-```python title=./src/myproject/v1/server_config.proto-valdator
+```python title=./src/myproject/v1/server_config.proto-validator
 load("//myproject/v1/server_config.proto", "ServerConfiguration")
 
 def validate_server_config(config):

docusaurus.config.js

@@ -1,8 +1,7 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+import { themes as prismThemes } from 'prism-react-renderer';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -53,8 +52,10 @@ const config = {
           lastVersion: 'current',
           versions: {
             current: {
+              label: 'v0.2.0',
+            },
+            "0.1.7": {
               label: 'v0.1.7',
-              path: '0.1.7',
             }
           }
         },
@@ -85,6 +86,12 @@ const config = {
           srcDark: 'img/protoconf_inverse.png',
         },
         items: [
+          {
+            type: 'doc',
+            docId: 'getting-started/getting-started',
+            position: 'left',
+            label: 'Get Started',
+          },
           {
             type: 'doc',
             docId: 'intro',
@@ -148,7 +155,7 @@ const config = {
             items: [
               {
                 label: 'Tutorial',
-                to: 'docs/0.1.7/intro',
+                to: 'docs/intro',
               },
             ],
           },
@@ -188,8 +195,8 @@ const config = {
         },
       },
       prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
+        theme: prismThemes.oneLight,
+        darkTheme: prismThemes.oneDark,
         additionalLanguages: ['protobuf', 'rust', 'java', 'docker' ],
       },
     }),

package.json

@@ -15,18 +15,18 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.0.0",
-    "@docusaurus/plugin-google-gtag": "^2.4.1",
-    "@docusaurus/preset-classic": "^3.0.0",
-    "@docusaurus/theme-mermaid": "^3.0.0",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/plugin-google-gtag": "^3.4.0",
+    "@docusaurus/preset-classic": "^3.4.0",
+    "@docusaurus/theme-mermaid": "^3.4.0",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "prism-react-renderer": "^2.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.4.0",
+    "@docusaurus/module-type-aliases": "^3.4.0",
     "@tsconfig/docusaurus": "^2.0.0",
     "typescript": "^5.0.0"
   },
@@ -45,4 +45,4 @@
   "engines": {
     "node": ">=16.14"
   }
-}
+}

src/pages/index.tsx

@@ -17,7 +17,7 @@ function HomepageHeader() {
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"
-            to="/docs/0.1.7/intro">
+            to="/docs/intro">
             Getting Started
           </Link>
         </div>

src/theme/CodeBlock/Line/index.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import Line from '@theme-original/CodeBlock/Line';
+
+export default function LineWrapper(props) {
+  return (
+    <>
+      <Line {...props} />
+    </>
+  );
+}

versions.json

@@ -0,0 +1,3 @@
+[
+  "0.1.7"
+]