(api definitions) Clarify protobuf spec setup, add protobuf generators reference (#1242)

Author: devalog

fern/products/api-def/api-def.yml

@@ -213,6 +213,8 @@ navigation:
           - page: Error handling
             path: ./grpc-pages/services/errors.mdx
             slug: errors
+      - page: generators.yml reference
+        path: ./grpc-pages/reference/generators-reference.mdx
   - section: Fern Definition
     collapsed: true
     slug: ferndef

fern/products/api-def/grpc-pages/overview.mdx

@@ -6,7 +6,7 @@ description: gRPC is a high-performance RPC framework that uses Protocol Buffers
 <Markdown src="/snippets/enterprise-plan.mdx"/>
 
 <Note>
-  Fern only supports gRPC SDK generation for .NET/C#.
+  Fern only supports gRPC SDK generation for .NET/C#. Protobuf specs can be used for documentation generation in all languages.
 </Note>
 
 gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. It uses Protocol Buffers (protobuf) as the interface definition language and supports multiple programming languages. 
@@ -202,20 +202,21 @@ fern/
 ```
 </Step>
 <Step title="Create a `generators.yml` file">
-Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files:
+Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files. See [gRPC generators.yml reference](/api-definitions/grpc/generators-yml-reference) for complete configuration options.
 
 ```yaml title="generators.yml"
 # Your API definition
 api: 
   specs: 
     - proto:
-        root: ./proto
-        target: ./proto/user_service.proto
-
+        # Path up to where package starts (e.g., for package userservice.v1)
+        root: ../user-service/proto 
+        # Omit to generate docs for entire root folder
+        target: ../user-service/proto/data/v1/user_service.proto 
 groups:
   external:
     generators:
-      # Your generator configurations here
+      # Your C# generator configuration here, if relevant
 ```
 
 Your final directory structure:

fern/products/api-def/grpc-pages/reference/generators-reference.mdx

@@ -0,0 +1,8 @@
+---
+title: gRPC generators.yml reference
+description: Reference for configuring gRPC specifications in your generators.yml file
+---
+
+Configure how your gRPC specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file.
+
+<Markdown src="/snippets/grpc-specs.mdx" />

fern/products/sdks/reference/generators-yml-reference.mdx

@@ -226,31 +226,7 @@ api:
 </ParamField>
 </Accordion>
 <Accordion title="gRPC/proto buffers">
-
-```yaml title="generators.yml"
-api:
-  specs:
-    - proto:
-        root: "./proto"
-        target: "proto/service/v1/service.proto"
-        local-generation: true
-```
-
-<ParamField path="root" type="string" required={true} toc={true}>
-  Path to the `.proto` directory root (e.g., `proto`).
-</ParamField>
-
-<ParamField path="target" type="string" toc={true}>
-  Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`).
-</ParamField>
-
-<ParamField path="overrides" type="string" toc={true}>
-  Path to the overrides configuration.
-</ParamField>
-
-<ParamField path="local-generation" type="boolean" default="false" toc={true}>
-  Whether to compile `.proto` files locally. Defaults to remote generation (`false`).
-</ParamField>
+<Markdown src="/snippets/grpc-specs.mdx" />
 </Accordion>
 <Accordion title="OpenRPC">
 

fern/snippets/grpc-specs.mdx

@@ -0,0 +1,24 @@
+```yaml title="generators.yml"
+api:
+  specs:
+    - proto:
+        root: "./proto"
+        target: "proto/service/v1/service.proto"
+        local-generation: true
+```
+
+<ParamField path="root" type="string" required={true} toc={true}>
+  Path to the `.proto` directory root (e.g., `proto`). Must be specified up to where the package starts. For example, if your package is `package.test.v1` at the file path `protos/package/test/v1/test_file.proto`, the root should be `protos/`
+</ParamField>
+
+<ParamField path="target" type="string" toc={true} required={false}>
+  Path to the target `.proto` file (e.g., `proto/user/v1/user.proto`). Omit to generate docs for the entire root folder. 
+</ParamField>
+
+<ParamField path="overrides" type="string" toc={true}>
+  Path to the overrides configuration file. Used for SDK generation only, not for documentation generation.
+</ParamField>
+
+<ParamField path="local-generation" type="boolean" default="false" toc={true}>
+  Whether to compile `.proto` files locally. Defaults to remote generation (`false`).
+</ParamField>