[feat] Generate markdown documentation for gRPC services

[JasterV]

This PR implements a new subcommand doc that generates markdown documentation for a given gRPC service!

Description

For the most part, the inner logic of this subcommand is the same as the describe, the only thing that changes is the way that the found descriptor is transformed to a final output.

In this case, a Packages type has been implemented to transform a ServiceDescriptor into a map of Packages.

Each package groups all the file descriptors with the same package name (or namespace).

A Package contains all the necessary information for a file of documentation to be generated (All its contained services, messages and enum descriptors and its name).

The output of this command is a folder with all the generated documentation, which contains a file per protobuf package.

Introduced the granc-test-support crate

• Renamed the echo_service crate as granc-test-support, providing both the definition of a protobuf service for integration testing and a function to compile protobuffer at runtime into a file descriptor (Potentially this could be used to let users pass a folder to a proto project in addition to the server reflection and the local file descriptor options. For example, the call command could compile a file descriptor on the fly from a folder containing a protobuffer project before making the call to the gRPC server.

Descriptor API Enhancements:

• Added name, full_name, and package_name methods to the Descriptor enum to simplify access to descriptor metadata. (granc-core/src/client/types.rs)

Dependency Management Improvements:

• Added grouping for gRPC-related dependencies in dependabot.yml for improved automated dependency updates. (.github/dependabot.yml)

[JasterV]

Gemini's two cents on the choice of making this a separate command:

---

Yes, I strictly believe that having a separate docs command (or doc) is the superior User Experience choice compared to burying it under describe.

Here is the breakdown of why, along with alternative UX strategies to consider.

Why docs should be separate from describe

1. Difference in User Intent (The "Jobs to be Done" Framework)

• granc describe: The user is in "Debugging/Coding Mode." They are likely in the terminal, writing a granc call command, and forgot a field name. They want quick, ephemeral info printed to stdout so they can copy-paste it.
• granc docs: The user is in "Documentation/Sharing Mode." They want to generate a permanent artifact to read later, host on a wiki, or share with a colleague. They expect side effects (creating files/folders).

Mixing these intents confuses the command's purpose.

2. Input/Output Mismatch

• describe is designed to pipe to stdout.

• Current behavior: println!("{}", FormattedString...).

• docs is designed to write to the File System.

• Current behavior: fs::create_dir_all and fs::write.

• If you combine them (granc describe --markdown), the user has to handle the mental load of: "If I don't pass --output, does it dump markdown to my terminal? Or does it create a folder? If so, which folder?"

3. Alignment with Ecosystem Standards

Since granc is a Rust tool, mimicking the Rust toolchain is a massive UX win.

• Rust: Uses cargo doc (generates HTML/files), separate from cargo metadata or cargo tree (introspection).
• Go: Uses go doc.
• Python: Uses pydoc.

Users intuitively understand that doc/docs means "generate reference material."

---

Alternative Options for Best UX

While docs is great, here are two other architectural patterns depending on your long-term vision for granc.

Option A: The "Export" Pattern (Future-Proofing)

If you plan to support generating other artifacts later (e.g., OpenAPI/Swagger specs, JSON Schemas, or HTML), docs might be too narrow.
Command: granc export <FORMAT> <SYMBOL>

• granc export markdown my.Service
• granc export openapi my.Service
• granc export json-schema my.Message

Verdict: Use this only if you definitely plan to support non-markdown exports soon. Otherwise, it adds unnecessary typing.

Option B: The "Interactive" Pattern (The Gold Standard)

If you keep docs, you can enhance the UX by making it behave like cargo doc --open.

1. Add an --open flag:
   After generating the markdown, try to open the index.md in the user's default markdown viewer or browser.
2. Add a --serve flag:
   Spin up a tiny HTTP server to view the docs (if you eventually move to HTML).

Recommended Refinement

I suggest sticking with the separate command, but I recommend renaming the command from docs to doc (singular) to match cargo doc, go doc, and rustdoc. It feels slightly more "native" to a CLI.

Proposed CLI structure:

# 1. Quick introspection (stdout)
granc describe my.package.Service

# 2. Artifact generation (filesystem)
granc doc my.package.Service --output ./wiki

This keeps the separation of concerns clear: Introspection vs. Generation.