Docs for Rust devs

[naveen-ravi2810]

Creating docs for the rust developers in specific to up-rust

addresses 176

[sophokles73]

@naveen-ravi2810 I appreciate the effort of trying to improve the documentation 👍
What we are in need of is more practical developer guidance by means of examples etc which supports developers in using the API. The kind of documentation that you have put into this draft so far seems to be more focused on generic concepts in Rust and Git. FMPOV users will either already know that or will not have a hard time figuring it out based on existing Rust and Git documentation (available online).

[naveen-ravi2810]

@naveen-ravi2810 I appreciate the effort of trying to improve the documentation 👍 What we are in need of is more practical developer guidance by means of examples etc which supports developers in using the API. The kind of documentation that you have put into this draft so far seems to be more focused on generic concepts in Rust and Git. FMPOV users will either already know that or will not have a hard time figuring it out based on existing Rust and Git documentation (available online).

Understood @sophokles73
I will make the documentation for the API's examples

[PLeVasseur]

Hey @sophokles73 -- to make sure we set @naveen-ravi2810 up the right way, which format would the documentation be the most helpful do you think?

I can think of a few:

1. flesh out more doc comments with elaborated examples
2. add examples to an examples/ folder which shows how to use up-rust
3. markdown documentation in the repo
4. MDBook which documents usage which is eventually deployed to e.g. GitHub Pages, maybe even a subdomain on uprotocol.org

My 2c: start with 3. with plans to eventually turn into 4.

What do you think?

[sayyedkamran]

Hello @naveen-ravi2810 and @sophokles73, @PLeVasseur 

I saw the discussion regarding the need for more practical API guidance and examples in the Rust Developers Guide 

I'd like to take ownership of this missing content and push this PR forward. I plan to focus on creating the necessary Markdown documentation sections. I will ensure the content directly aligns with the request for API usage examples rather than general Rust concepts.

Do you have any further advice or a preferred starting point (e.g., focus on UUri first, or a complete Pub/Sub example)?

Thanks!

[sophokles73]

@sayyedkamran thanks for joining in 👍

Do you have any further advice or a preferred starting point (e.g., focus on UUri first, or a complete Pub/Sub example)?

We do have some example code in the examples folder. Maybe you can start off with adding more comments to these examples and then add a section in the markdown documentation which walks through one of the examples (PubSub) and touches on things like what the UUris are used for (source, sink) and general properties of messages, what the role of Transports is and how you could easily swap out one transport for the other in the example. IMHO you should not get down each rabbit hole but provide a little more context so developers can better understand why they need to do what is being done in the example code. For more information you should then provide pointers to the spec etc.

[sayyedkamran]

Thanks @sophokles73 for the guidance please.