Skip to content

Move code examples to rustdoc with compilation #4

@dannywillems

Description

@dannywillems

Description

Code examples on the documentation website (https://leakix.github.io/oxide-sql/) should be:

  1. Stored in rustdoc comments in the source code
  2. Compiled during doc generation to ensure they're always valid
  3. Referenced from the website, not duplicated

Current State

  • Code examples are duplicated in markdown files
  • Examples may become stale if API changes

Desired State

  • Code lives in rustdoc comments with /// or //!
  • Examples use # to hide boilerplate
  • CI compiles all doc examples (cargo test --doc)
  • Website pages link to rustdoc for examples

References

  • Similar to how o1-labs/mina-rust handles documentation
  • Docusaurus can redirect to docs.rs pages

Tasks

  • Move examples from doc/docs/schema/queries.md to rustdoc
  • Ensure all examples compile with cargo test --doc
  • Update website to link to rustdoc instead of inline code
  • Add CI step to test doc examples

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions