Commit Graph

3 Commits

Author SHA1 Message Date
hasura-bot
a2e6e50e27 Fix broken links
GITHUB_PR_NUMBER: 9138
GITHUB_PR_URL: https://github.com/hasura/graphql-engine/pull/9138

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6462
Co-authored-by: arpitpandey0209 <9442768+arpitpandey0209@users.noreply.github.com>
GitOrigin-RevId: 85ce1a190477803f553deb31c1c95b512fa3fca0
2022-10-26 14:22:19 +00:00
Antoine Leblanc
8a999bd44d Structural updates to the server's engineering documentation
### Description

This PR does several things:
- it cleans up some structural issues with the engineering documentation:
  - it harmonizes the table of contents structure across different files
  - adds a link to the bigquery documentation
  - moves some files to a new `deep-dives` subfolder
  - puts a title at the top of each page to avoid github assuming their title is "table of contents"
- it pre-fills the glossary with a long list of words that could use an entry (all empty for now)
- it adds the only remaining relevant server file from [hasura-internal's wiki](https://github.com/hasura/graphql-engine-internal/wiki): the old "multiple backends architecture" file

### Discussion

A few things worth discussing in the scope of this PR:
- is it worth migrating old documentation such as the multiple backends architecture, that document a decision process rather instead of being up-to-date reflections of the code? are we planning to delete hasura-internal?
- should we focus instead on _new_ documentation, aimed to be kept up to date?
- are there other old documents we want to move in here, or is that it?
- is this glossary structure ok, or would a purely alphabetical structure make sense?
- does it make sense to have the glossary only in the engineering section? more generally, _what's our broader plan for documentation_?

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4537
GitOrigin-RevId: c2b674657b19af7a75f66a2a304c80c30f5b0afb
2022-05-30 09:46:06 +00:00
Antoine Leblanc
75d374bf26 Add new documentation folder and two documentation files
As discussed on Slack, we're thinking of updating the documentation that was in the old graphql-engine wiki, and bring it to the repo. This PR creates the new folder, and adds two pieces of documentation: a high-level overview of the system, and a description of our schema-building code (the so-called "PDV parsers").

One thing to be discussed: how do we do cross-file references? To an extent, this will depend on what tool we use for rendering them, to where we upload the generated files.

Another point is: we should update our CI to avoid running tests on changes in `server/documentation`.

Rendered:
- [high level overview](https://github.com/hasura/graphql-engine-mono/blob/nicuveo/server-docs/server/documentation/overview.md)
- [schema code](https://github.com/hasura/graphql-engine-mono/blob/nicuveo/server-docs/server/documentation/schema.md)

https://github.com/hasura/graphql-engine-mono/pull/2219

GitOrigin-RevId: f729616d28e8f2f30c0a07583b53460510bafd80
2021-09-15 10:04:24 +00:00