Documentation

[obmarg]

Thinking I should write something with mdBook for this - maybe an inside->out guide, starting with how to use the selection set functions directly, then through to query_dsl, then through to the various derives?

[obmarg]

Rough plan for this:

1. Get cynic querygen deployed (Deploy cynic-querygen #54)
2. Build an example app or two using cynic - record this, edit & upload to youtube
3. Write a walkthrough of the process for 2, add it to the book
4. Write the rest of the book, according to this rough outline:

• An Intro

• Quickstart

  • Prerequisites (i.e. a graphql schema, query, rust project)
  • Take people through adding dependencies, running things through querygen.
  • Adding code to actually make a query.
  • Maybe outline common pitfalls.
  • Link to somewhere that explains how to do a build.rs rather than query_dsl implementation

• Tutorial

  • Figure out a quick project that we can take people through.

  • Maybe a real simple star wars one

  • Followed by a more complex github one (possibly based somewhat off viktors github thing)

  • Though ideally need to find a way to make the github one compile fast - possibly moving the query_dsl
    to it's own file would allow incremental compilation to usually skip it.

  • Definitely detail snapshot testing trick for viewing queries here.

  • Could possibly livestream this stuff also.

Next up, details on the various traits and how they link together/form queries:

• Query Fragments
  • An explanation of what they are
  • An example of deriving one
  • Details of the functions it exposes
  • How to turn one into a query
  • Attributes?
  • Link to other docs that show how to build a query fragment manually.
• Enums
  • Explanation
  • Example of derive
  • Attributes
  • Example of actualy implementing one
• Similar for interfaces, union types, inline fragments etc.

Then, details of how the query dsl works:

• The Query DSL

  • What it is, why it's needed
  • Example of calling it manually (including how this links to query fragments).
  • Selection structs
  • Selection builders
  • Marker types

• Building Queries Manually

  • Selection sets
    • Scalar selectors
    • Field selectors
    • map functions
    • and_then etc.
  • type locks (possibly touch on this in The Query DSL also)

• Common issues/FAQ/troubleshooting

[obmarg]

Definitely not finished with the documentation, but I think I've done enough that this issue has served its purpose.