update docs

README.md

@@ -22,7 +22,7 @@ It is heavily inspired by tools like `grpcurl` but built to leverage the safety
 * **Server Reflection**: Can fetch schemas directly from the server, removing the need to pass a local file descriptor set file (`.bin` or `.pb`).
 * **Introspection Tools**: Commands to list services and describe services, messages, and enums.
   * **Local Introspection**: In addition to making network requests, Granc can also be used as a local introspection tool for file descriptor binary files. You can load a local `.bin` file to inspect services, messages, and enums without needing to fetch the schema from a server.
-* **Documentation Generator**: Generate static, cross-linked Markdown documentation for your services and types directly from the schema.
+* **Documentation Generator**: Generate static, cross-linked Markdown documentation for your services and types directly from the schema. [See a real example](./examples/docs/index.md) generated from this repo's [example protos](./examples/proto/library).
 * **Zero Compilation Dependencies**: Does not require generating Rust code for your protos. Just point to a descriptor file.
 * **Tonic 0.14**: Built on the latest stable Rust gRPC stack.
 
@@ -211,12 +211,11 @@ Generates static Markdown documentation for a specific service and its dependenc
 
 ```bash
 granc doc <SYMBOL> --output <DIR> [OPTIONS]
-
 ```
 
 | Argument/Flag | Short | Description |
 | --- | --- | --- |
-| `<SYMBOL>` |  | Fully qualified name of the Service (e.g., `my.package.Service`). |
+| `<SYMBOL>` |  | Fully qualified name of the Service (e.g., `library.LibraryService`). |
 | `--output` | `-o` | Directory where the markdown files will be generated. |
 | `--uri` | `-u` | Use Server Reflection to resolve the schema. |
 | `--file-descriptor-set` | `-f` | Use a local file to resolve the schema (offline). |
@@ -230,9 +229,12 @@ granc doc helloworld.Greeter --uri http://localhost:50051 --output ./docs
 **Generating docs from a file:**
 
 ```bash
-granc doc helloworld.Greeter --file-descriptor-set ./descriptors.bin --output ./docs
+granc doc library.LibraryService --file-descriptor-set examples/library.bin --output ./docs
 ```
 
+Check out the full [generated documentation example](./examples/docs/index.md) included in this repository.
+These documents were generated directly from the [library example protos](./examples/proto/library) using the command above.
+
 ## 🔮 Roadmap
 
 * **Interactive Mode**: A REPL for streaming requests interactively.

examples/docs/index.md

@@ -0,0 +1,12 @@
+# Documentation Index
+
+
+## Service
+
+- [**LibraryService**](library.md#LibraryService)
+
+## Packages
+
+- [library](library.md)
+- [library.domain](library.domain.md)
+- [library.rpc](library.rpc.md)

examples/docs/library.domain.md

@@ -0,0 +1,86 @@
+<a id="Author"></a>
+## Author
+
+### Definition
+
+```protobuf
+package library.domain;
+
+message Author {
+  string  id = 1;
+  string  full_name = 2;
+  repeated library.domain.Book  bibliography = 3;
+}
+```
+
+### Dependencies
+
+- Field `bibliography`: [Book](library.domain.md#Book)
+
+---
+
+<a id="Book"></a>
+## Book
+
+### Definition
+
+```protobuf
+package library.domain;
+
+message Book {
+  string  isbn = 1;
+  string  title = 2;
+  library.domain.Author  author = 3;
+  library.domain.Publisher  publisher = 4;
+  library.domain.Genre  genre = 5;
+}
+```
+
+### Dependencies
+
+- Field `author`: [Author](library.domain.md#Author)
+- Field `publisher`: [Publisher](library.domain.md#Publisher)
+- Field `genre`: [Genre](library.domain.md#Genre)
+
+---
+
+<a id="Publisher"></a>
+## Publisher
+
+### Definition
+
+```protobuf
+package library.domain;
+
+message Publisher {
+  string  id = 1;
+  string  name = 2;
+  string  address = 3;
+}
+```
+
+### Dependencies
+
+*None*
+
+---
+
+<a id="Genre"></a>
+## Genre
+
+### Definition
+
+```protobuf
+package library.domain;
+
+enum Genre {
+  UNKNOWN = 0;
+  FICTION = 1;
+  NON_FICTION = 2;
+  SCI_FI = 3;
+  HISTORY = 4;
+}
+```
+
+---
+

examples/docs/library.md

@@ -0,0 +1,44 @@
+<a id="LibraryService"></a>
+## LibraryService
+
+### Definition
+
+```protobuf
+package library;
+
+service LibraryService {
+  rpc GetBook(library.rpc.GetBookRequest) returns (library.domain.Book);
+
+  rpc QueryBooks(library.rpc.QueryBooksRequest) returns (stream library.domain.Book);
+
+  rpc Checkout(stream library.rpc.CheckoutRequest) returns (library.rpc.CheckoutResponse);
+
+  rpc SupportChat(stream library.rpc.ChatMessage) returns (stream library.rpc.ChatMessage);
+
+}
+```
+
+### Methods
+
+#### `GetBook`
+
+- Request: [GetBookRequest](library.rpc.md#GetBookRequest)
+- Response: [Book](library.domain.md#Book)
+
+#### `QueryBooks`
+
+- Request: [QueryBooksRequest](library.rpc.md#QueryBooksRequest)
+- Response: [Book](library.domain.md#Book)
+
+#### `Checkout`
+
+- Request: [CheckoutRequest](library.rpc.md#CheckoutRequest)
+- Response: [CheckoutResponse](library.rpc.md#CheckoutResponse)
+
+#### `SupportChat`
+
+- Request: [ChatMessage](library.rpc.md#ChatMessage)
+- Response: [ChatMessage](library.rpc.md#ChatMessage)
+
+---
+

examples/docs/library.rpc.md

@@ -0,0 +1,100 @@
+<a id="ChatMessage"></a>
+## ChatMessage
+
+### Definition
+
+```protobuf
+package library.rpc;
+
+message ChatMessage {
+  string  user_id = 1;
+  string  text = 2;
+  int64  timestamp = 3;
+}
+```
+
+### Dependencies
+
+*None*
+
+---
+
+<a id="CheckoutRequest"></a>
+## CheckoutRequest
+
+### Definition
+
+```protobuf
+package library.rpc;
+
+message CheckoutRequest {
+  string  isbn = 1;
+}
+```
+
+### Dependencies
+
+*None*
+
+---
+
+<a id="CheckoutResponse"></a>
+## CheckoutResponse
+
+### Definition
+
+```protobuf
+package library.rpc;
+
+message CheckoutResponse {
+  repeated library.domain.Book  checked_out_books = 1;
+  int32  total_items = 2;
+  string  due_date = 3;
+}
+```
+
+### Dependencies
+
+- Field `checked_out_books`: [Book](library.domain.md#Book)
+
+---
+
+<a id="GetBookRequest"></a>
+## GetBookRequest
+
+### Definition
+
+```protobuf
+package library.rpc;
+
+message GetBookRequest {
+  string  isbn = 1;
+}
+```
+
+### Dependencies
+
+*None*
+
+---
+
+<a id="QueryBooksRequest"></a>
+## QueryBooksRequest
+
+### Definition
+
+```protobuf
+package library.rpc;
+
+message QueryBooksRequest {
+  string  title_prefix = 1;
+  library.domain.Genre  genre_filter = 2;
+}
+```
+
+### Dependencies
+
+- Field `genre_filter`: [Genre](library.domain.md#Genre)
+
+---
+

examples/proto/library/domain.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+package library.domain;
+
+enum Genre {
+  UNKNOWN = 0;
+  FICTION = 1;
+  NON_FICTION = 2;
+  SCI_FI = 3;
+  HISTORY = 4;
+}
+
+message Publisher {
+  string id = 1;
+  string name = 2;
+  string address = 3;
+}
+
+// Represents a Book in the collection.
+message Book {
+  string isbn = 1;
+  string title = 2;
+  
+  // Circular Dependency: Book references Author (valid since they are in the same file)
+  Author author = 3;
+  
+  Publisher publisher = 4;
+  
+  Genre genre = 5;
+}
+
+message Author {
+  string id = 1;
+  string full_name = 2;
+  
+  // Circular Dependency: Author references Book
+  repeated Book bibliography = 3;
+}

examples/proto/library/rpc.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package library.rpc;
+
+import "library/domain.proto";
+
+message GetBookRequest {
+  string isbn = 1;
+}
+
+message QueryBooksRequest {
+  string title_prefix = 1;
+  // Reusing the Genre enum from domain.proto
+  library.domain.Genre genre_filter = 2;
+}
+
+message CheckoutRequest {
+  string isbn = 1;
+}
+
+message CheckoutResponse {
+  // Reusing Book type
+  repeated library.domain.Book checked_out_books = 1;
+  int32 total_items = 2;
+  string due_date = 3;
+}
+
+message ChatMessage {
+  string user_id = 1;
+  string text = 2;
+  int64 timestamp = 3;
+}

examples/proto/library/service.proto

@@ -0,0 +1,21 @@
+syntax = "proto3";
+
+package library;
+
+import "library/domain.proto";
+import "library/rpc.proto";
+
+// Service for managing a collection of books and authors.
+service LibraryService {
+  // Unary
+  rpc GetBook(library.rpc.GetBookRequest) returns (library.domain.Book);
+
+  // Server Streaming
+  rpc QueryBooks(library.rpc.QueryBooksRequest) returns (stream library.domain.Book);
+
+  // Client Streaming
+  rpc Checkout(stream library.rpc.CheckoutRequest) returns (library.rpc.CheckoutResponse);
+
+  // Bidirectional
+  rpc SupportChat(stream library.rpc.ChatMessage) returns (stream library.rpc.ChatMessage);
+}