About the API Reference

This section provides access to the low-level API documentation for the various projects within the Firestone ecosystem. Unlike the narrative guides, which explain how to use the tools, the API reference is a detailed, automatically generated documentation of the source code itself—including modules, classes, functions, and their signatures.

Docs-from-Code Philosophy

A core principle of the Firestone project is that API documentation should be generated directly from the source code. This ensures that the reference is always up-to-date and accurately reflects the implementation.

• For Python projects (firestone, firestone-lib), the reference is generated from Python docstrings using pdoc.
• For the bindy Rust project, the Custom Resource Definition (CRD) reference is generated from Rust doc comments using a custom crddoc tool.
• For the bindcar Rust project, the reference is the standard HTML documentation generated by rustdoc.

What You Will Find Here

This section is divided into guides for the different types of API references available. You will learn:

• How to generate each type of API reference.
• How to interpret the generated documentation.
• How to contribute to the documentation by improving the source code comments and docstrings.

Who Should Use the API Reference?

The API reference is intended for developers who are:

• Extending Firestone: If you are building a new feature or fixing a bug, the API reference is an essential tool for understanding the internal workings of the codebase.
• Deeply Integrating with Firestone: If you are building complex integrations that go beyond the standard CLI or REST API usage, you may need to interact with the Python or Rust APIs directly.
• Troubleshooting: When a high-level guide is not enough, the API reference provides the ground truth of the code's behavior.

For most users, the Getting Started Guide and Best Practices will be more than sufficient. This section is for those who need to dive deeper into the code itself.