docs: align Rust guide structure with JS

[alexcamposruiz]

Summary

• Reworked Rust docs to align with JS doc structure while staying accurate to the Rust API.
• Expanded guide content for configuration, connector lifecycle, input/output workflows, data access, errors, threading, and advanced operations.
• Incorporated previous content
• Cleaned up crate index to a consistent TOC plus API Overview.

Details

Where Previous Content Moved

• Overview / API summary: now under “API Overview” on the crate index.
• Build-time linking details: now in docs/guide/getting_started.md.
• Typed data support: now in docs/guide/data.md.
• Error handling: now in docs/guide/errors.md.
• Thread safety: now in docs/guide/threading.md.

Areas Needing More Work

JS Parity Gaps

These are potential improvements, but may not be necessary for now:

• Configuration: JS includes a deeper XML/IDL walkthrough and more tag‑by‑tag mapping; Rust version is shorter.
• Data access: JS includes local field‑name syntax examples and a large XML/IDL sample; Rust relies on external links.
• Threading: JS lists specific safe/unsafe operations and reentrancy caveats; Rust guide is high‑level.
• Error handling: JS shows richer error classes/scenarios; Rust guide has fewer concrete cases.
• Advanced: JS has a richer “features” content tree; Rust guide is a concise checklist.

Other

• Move Rust snippets in docs to .rs files and include them in .md so they can be compiled
• Expand concrete XML/IDL examples in Configuration and Data access.
• Add more “common failure modes” examples in Error handling.
• Clarify any Rust threading guarantees if an authoritative contract exists.
• Document matched publication/subscription JSON formats.

[alejnp]

My biggest concern with this is the added maintainability burden (external URLs, duplicated content), but otherwise I'm okay with keeping it if deemed useful for customers.

@lloadholt I've added you as reviewer because most of this is documentation. You can find the internal-only, built documentation here.

[alexcamposruiz]

My biggest concern with this is the added maintainability burden (external URLs, duplicated content), but otherwise I'm okay with keeping it if deemed useful for customers.

@lloadholt I've added you as reviewer because most of this is documentation. You can find the internal-only, built documentation here.

Duplication is a concern, but is something we long ago decided was a lesser evil in the Connectors. Trying to consolidate docs for all Connectors would be harder to implement and maintain that some limited duplication.

[alexcamposruiz]

My biggest concern with this is the added maintainability burden (external URLs, duplicated content), but otherwise I'm okay with keeping it if deemed useful for customers.

@lloadholt I've added you as reviewer because most of this is documentation. You can find the internal-only, built documentation here.

@lloadholt - Most of this documentation is adapted from the JavaScript connector, so I don't think it requires a deep review.

[lloadholt]

Commented through 'getting-started.md'.

[lloadholt]

Commented remaining md files (index.md through result.md)

[lloadholt]

@alexcamposruiz No further comments on the content.

Is it ok for me to edit these files (and the Connector for JavaScript manual) directly to apply RTI style? Primarily, I'd like to change the text format for the following words to match the format used in other RTI user manuals:

• Topics
• DataReader (replace all instances of "reader")
• DataWriter (replace all instances of "writer")
• RTI Connector
• Publisher
• Subsriber

[alexcamposruiz]

@alexcamposruiz No further comments on the content.

Is it ok for me to edit these files (and the Connector for JavaScript manual) directly to apply RTI style? Primarily, I'd like to change the text format for the following words to match the format used in other RTI user manuals:

• Topics
• DataReader (replace all instances of "reader")
• DataWriter (replace all instances of "writer")
• RTI Connector
• Publisher
• Subsriber

@lloadholt Sure. Can you approve this PR and create new ones with your edits?

[alejnp]

I am merging this PR and deleting the branch. In the future, prefer making the changes in your own clone, to avoid issues with rulesets and avoid polluting the .git of the main repository.