Add documentation scaffolding for first sync-up.

## Description

This PR adds a basic README file to `server/documentation`, in order to get something somewhat decent when we run the first automatic sync.

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3468
GitOrigin-RevId: 10c3afc1ea02ee3eb914009e3b9ad22065c1db50
This commit is contained in:
Antoine Leblanc 2022-01-25 13:17:26 +00:00 committed by hasura-bot
parent 576c539bcb
commit 472d5df5ae
3 changed files with 67 additions and 6 deletions

View File

@ -0,0 +1,44 @@
# Server engineering documentation
This page documents the structure and the internal architecture of the [GraphQL
Engine Server](https://github.com/hasura/graphql-engine/tree/master/server). To
get started, you can read the [overview](overview.md). We also maintain a
[glossary](glossary.md) of all the terms we use throughout the code and the
documentation.
You can also get started with a list of [tips and tricks](tips.md).
## Haddock documentation
You can browse the generated [haddock documentation](haddock/) for the engine's
code; we automatically update it on every push to a branch of interest:
* [stable branch](haddock/stable)
* [alpha branch](haddock/alpha)
* [beta branch](haddock/beta)
* [main branch](haddock/main)
## Architecture deep-dive
* how to understand our [GraphQL schema](schema.md)
* how to perform [database migrations](migration-guidelines.md)
TODO: we can either list individual topics here, or point to architecture/ and have a README file there.
## Notes
In our Haskell codebase, we use [GHC-style
notes](https://www.stackbuilders.com/news/the-notes-of-ghc) 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](notes/).
## Updating this documentation
All markdown files in this folder are either copied *verbatim* from
[`server/documentation`](https://github.com/hasura/graphql-engine/tree/master/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"`.

View File

@ -0,0 +1,11 @@
# Glossary
TODO.
### Subscriptions
TODO
### Livequeries
See [Subscriptions](#subscriptions).

View File

@ -1,7 +1,13 @@
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
<!--
Please make sure you update the table of contents when modifying this file. If
you're using emacs, you can generate a default version of it with `M-x
markdown-toc-refresh-toc` (provided by the package markdown-toc), and then edit
it for readability.
-->
<!-- markdown-toc start -->
**Table of Contents**
- [Tips and tricks](#tips-and-tricks)
- [Use curl and yaml2json to test the graphql-engine API directly](#use-curl-and-yaml2json-to-test-the-graphql-engine-api-directly)
- [Convert a test case to a live example](#convert-a-test-case-to-a-live-example)
- [Run a remote MSSQL instance with dev.sh](#run-a-remote-mssql-instance-with-devsh)