WIP: Add seaography documentation #41
Conversation
✅ Deploy Preview for seaql ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
Also, why doesn't this link work? https://deploy-preview-41--seaql.netlify.app/Seaography It seems like docusaurus is not correctly set up? |
Seaography/docs/01-index.md
Outdated
|
|
||
| * Recommended to study, but not required | ||
|
|
||
| ## How to use |
There was a problem hiding this comment.
I am hoping to see a more comprehensive step by step guide, from the sample database to running GraphQL queries, perhaps with a few screenshots along the way if that help illustrate. Actually, if you have the energy, a short video screencast would be perfect! (It's not necessary though)
But yeah at least you get the idea, something like:
- Install the prerequisites
- Load the sample database
- Run the codegen
- Compile the Rust project
- Make GraphQL queries!
There was a problem hiding this comment.
Great point.
I will create a page "How to run the example database" and document the step by step process using pictures.
Regarding the video I will take a note of it and work on it on the future.
| let schema = Schema::build(QueryRoot, EmptyMutation, EmptySubscription) | ||
| .data(database) | ||
| .data(orm_dataloader) | ||
| .limit_complexity(5) |
There was a problem hiding this comment.
I think we always want to limit the complexity in practice. So I think the codegen should always generate this clause. And actually we can allow the user to config this number via the cli parameter.
5 sounds like a reasonable default!
This chapter can still discuss this topic.
There was a problem hiding this comment.
I can add it and be CLI driven
|
Also, I think we need one chapter discussing scaler filter and pagination, with a GraphQL input and a SQL output (sounds a lot like the test suite?) And another chapter for relational query. We should first select 2 or 3 tables with relation from the sample database and make several GraphQL queries against them. |
|
Finally, I think we need a chapter for some hints to how to customize the query mechanism and/or extend the GraphQL schema. I think we can also give a gentle introduction of GraphQL, how GraphQL resolvers work and perhaps comparison with other related GraphQL frameworks / engine. |
Because the netlify build command is not configured correct The current build command: How to fix it:
|
|
Hey @karatakis, I just make Netlify and GitHub Action to build docs using You can add seaography build script into |
I will try to give some details in the example page |
The "encancements-cookbook" is meant to be a chapter to explain how to extend the generated code. I will look to rename it and add more documentation on how to extend. Regarding the comparison between other GraphQL frameworks we cannot compare because we depend on async_graphql and it already has a comparison page here https://github.com/async-graphql/async-graphql/blob/master/feature-comparison.md Moreover we provide something else, we generate a GraphQL API, they provide GraphQL framework. |
* Initialize project
* [X] index page * [ ] tool internals page * [ ] generated project structure page * [ ] enchantments cookbok page
* [X] index page
* [X] tool internals page
* [ ] generated project structure page
* [ ] enchantments cookbok page
* fix links at index page
* [X] index page
* [X] tool internals page
* [X] generated project structure page
* [ ] real example page
* [ ] enchantments cookbok page
* remove real world example page
* add example graphql schema
* [X] index page
* [X] tool internals page
* [X] generated project structure page
* [X] enchantments cookbok page
* add Seaography on build.sh
* update index page, and getting started page * rename cookbook to extending code * add running example page
|
|
||
| ## Query examples | ||
|
|
||
| ### Fetch albums where artist ID = 1 || ID = 3 |
There was a problem hiding this comment.
Nice. I really liked these. This is where everything comes to live!
|
|
||
| Extra iterator adaptors, functions and macros. | ||
|
|
||
| * Recommended to study, but not required |
There was a problem hiding this comment.
The * makes this line being interpreted as a list. Consider escaping it :)
| * Recommended to study, but not required | |
| \* Recommended to study, but not required |
|
@karatakis Let me know when you want to publish an initial version of this |
|
@billy1624 how do we syntax highlight Rust?
|
|
Merged to the |
PR Info
Adds documentation for the new project of the SeaQL family Seaography.
Seaography is a CLI tool that generates a ready to compile Rust GraphQL API for a relational database.
The initial draft can be found here: SeaQL/summer-of-code#12