8a999bd44d
### 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 |
||
|---|---|---|
| .. | ||
| data-sources | ||
| deep-dives | ||
| glossary.md | ||
| overview.md | ||
| README.md | ||
| tips.md | ||
Server engineering documentation
This page documents the structure and the internal architecture of the GraphQL Engine Server. To get started, you can read the overview. We also maintain a glossary of all the terms we use throughout the code and the documentation.
You can also get started with a list of tips and tricks.
Haddock documentation
You can browse the generated haddock documentation for the engine's code; we automatically update it on every push to a branch of interest:
Architecture deep-dive
- how to understand our GraphQL schema
- how to perform database migrations
- how the execution of remote joins works
Backend-specific documentation
Notes
In our Haskell codebase, we use GHC-style
notes for long-form
comments detailing a specific aspect of the codebase. We gather all of them, as
of the main branch, in the notes subfolder.
Updating this documentation
All markdown files in this folder are either copied verbatim from
server/documentation
or generated as part of our CI; do not open a PR to modify files in
the gh-pages branch, and instead modify their source directly. Notes
are extracted using the scripts/extract-nodes bash script. The
haddock documentation is generated by running cabal haddock --haddock-internal --haddock-options="--ignore-all-exports".