Skip to content

Commit 3376f76

Browse files
EshaanAggEshaanAgg
authored
Add auto schema markdown generation to Talawa-API [Fixes part of PalisadoesFoundation#1240] (PalisadoesFoundation#1247)
* Add schema documentation * Add branch for testing * Fix docker action * Fix script * Remove docker * Bug fix * Move to correct workflow file * Remove docker files * Add documentation and change directory structure * Add schema export * Fix linting * Make required changes * Linting fix * Change commit message * Add docs directory * Add manual git command * Disable hooks in CI * Generate GraphQL Schema and Markdown Documentation * Better descriptions * Add docs to ESLint ignore * Upload schema.json as artifact * Sync * Fix movement * Bug fix * Syntax fix * Syntax fix * Bug fix * Add ls * Add ls * Change driectories * Add listing * Fix directory structure * Change branchname * Remove spec * Fix workflow * Generate GraphQL Schema and Markdown Documentation * Add secret authentication * Finalise tested workflow * Change token * Move get-graphql-schema to a dev dependency * Move to TALAWA_DOCS_SYNC token --------- Co-authored-by: EshaanAgg <[email protected]>
1 parent 68e6f74 commit 3376f76

10 files changed

+5776
-8
lines changed

‎.eslintignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@
33
build
44
coverage
55
node_modules
6-
src/types
6+
src/types
7+
docs/Schema.md

‎.github/workflows/push.yml

+64-5
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ jobs:
2525
# code coverage (post PR merge) is reported
2626
##############################################################################
2727

28-
Test-Application:
29-
name: Testing Application
28+
Push-Workflow:
29+
name: Testing Application and Updating Documentation
3030
runs-on: ubuntu-latest
3131
strategy:
3232
matrix:
@@ -46,9 +46,13 @@ jobs:
4646
ACCESS_TOKEN_SECRET: ${{ secrets.ACCESS_TOKEN_SECRET }}
4747
REFRESH_TOKEN_SECRET: ${{ secrets.REFRESH_TOKEN_SECRET }}
4848

49+
# We checkout the content of the Talawa-API repository in a directory called `api`
50+
# This is done as we will use the Talawa-Docs repository later too
4951
steps:
5052
- name: Checkout repository
5153
uses: actions/checkout@v3
54+
with:
55+
path: api
5256

5357
- name: Generate Access Token Secret
5458
run: echo "ACCESS_TOKEN_SECRET=$(openssl rand -hex 32)" >> $GITHUB_ENV
@@ -59,20 +63,75 @@ jobs:
5963
- name: Set up Node.js ${{ matrix.node-version }}
6064
uses: actions/setup-node@v3
6165

66+
# Move into the api folder before installing the dependencies
6267
- name: Install dependencies
63-
run: npm ci
68+
run: cd api && npm ci
6469

70+
# Move into the api folder before starting the server
71+
- name: Start the development server in detach mode
72+
run: |
73+
cd api && npm run dev &
74+
echo "Development server started..."
6575
- name: Sleep for 10s
6676
uses: juliangruber/sleep-action@v1
6777
with:
6878
time: 10s
6979

80+
# Move into the api folder before generating the Markdown schema documentation
81+
- name: Generate the GraphQL-Markdown documentation
82+
run: cd api && npm run generate:graphql-markdown
83+
84+
# Move into the api folder before generating the Schema is json form
85+
- name: Genrate the GraphQL Schema in JSON form
86+
run: cd api && npm run generate:graphql-schema
87+
88+
89+
# Running the generate::** scripts will create the necessary documentation on the server
90+
# where the GitHub Action is running locally. We add the same to stage with -f flag as they are a
91+
# part of the .gitignore file
92+
- name: Add the generated Markdown Documentation to stage
93+
run: cd api && git add docs/Schema.md -f
94+
95+
# We use this action to commit the changes above to the repository
96+
- name: Commit generated Markdown Documentation to the Talawa API repository
97+
uses: stefanzweifel/git-auto-commit-action@v4
98+
with:
99+
commit_message: Generate GraphQL Schema and Markdown Documentation
100+
repository: api
101+
102+
# We will clone the Talawa Docs in the folder called docs so that we can copy the generated
103+
# schema.json into the same later
104+
- name: Checkout the Talawa-Docs repository
105+
uses: actions/checkout@v3
106+
with:
107+
repository: PalisadoesFoundation/talawa-docs
108+
token: ${{ secrets.TALAWA_DOCS_SYNC }}
109+
path: docs
110+
111+
# Copy the generated schema.json into the Talawa Docs repository
112+
- name: Sync schema.json from Talawa API to Talawa Docs
113+
run: cp api/docs/schema.json docs/docs/
114+
115+
# Add the updated schema.json in Talawa Docs to stage
116+
- name: Add the synced schema.json to stage in Talawa Docs
117+
run: cd docs && git add docs/schema.json
118+
119+
# Commit the changes made to schema.json into Talawa Docs
120+
- name: Commit the synced schema to the Talawa Docs repository
121+
uses: stefanzweifel/git-auto-commit-action@v4
122+
with:
123+
commit_message: Update schema.json
124+
repository: docs
125+
126+
# Testing the application after moving into the api folder
70127
- name: Run the tests
71-
run: npm run test
128+
run: cd api && npm run test
72129

130+
# Upload Coverage
73131
- name: Present and upload coverage to Codecov as ${{env.CODECOV_UNIQUE_NAME}}
74132
uses: codecov/codecov-action@v3
75133
with:
134+
directory: api
76135
verbose: true
77136
fail_ci_if_error: false
78-
name: '${{env.CODECOV_UNIQUE_NAME}}'
137+
name: '${{env.CODECOV_UNIQUE_NAME}}'

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
# Add the auto-generated docs to .gitignore as the same are created by GitHub actions
2+
docs/Schema.md
3+
docs/schema.json
4+
15
node_modules
26
.idea
37
.env

‎.husky/pre-commit

+8
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
#!/usr/bin/env sh
2+
3+
# Disable the hooks in CI
4+
[ -n "$CI" ] && exit 0
5+
6+
# Change to the current directory
27
. "$(dirname -- "$0")/_/husky.sh"
38

49
# Formats code using prettier.
@@ -10,3 +15,6 @@ npm run typecheck
1015
# Checks and fixes all lint issues in code which don't require manual intervention.
1116
# Throws errors if lint issues requiring manual intervention are found in code.
1217
npm run lint:fix
18+
19+
# Add the changes made to the stage
20+
git add .

‎.prettierignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@
33
build
44
coverage
55
node_modules
6-
src/types
6+
src/types
7+
docs/Schema.md

‎CONTRIBUTING.md

+9
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ If you are new to contributing to open source, please read the Open Source Guide
2727
- [Pre-Commit hook](#pre-commit-hook)
2828
- [Post-Merge hook](#post-merge-hook)
2929
- [GraphQL Voyager](#graphql-voyager)
30+
- [GraphQL Markdown](#graphql-markdown)
3031
- [Running Queries with talawa-api](#running-queries-with-talawa-api)
3132
- [Internships](#internships)
3233
- [Community](#community)
@@ -273,6 +274,14 @@ Go to `http://localhost:4000/voyager` after running the development server to ex
273274
274275
![Voyager Demo for User Model](./image/GraphQL_Voyager.png)
275276
277+
### GraphQL Markdown
278+
279+
We use the [GraphQL Markdown](https://github.com/exogen/graphql-markdown) project to generate the documentation to describe the schema. To generate the same manually, you first need to start the development server locally with `npm run dev`, and then run the script `npm run generate:graphql-markdown`.
280+
281+
You can then view the [generated documentation here](./docs/Schema.md).
282+
283+
While we use a GitHub workflow to update ths schema documentation every time a PR is merged into the repository, it is highly advisable that if you making changes to the schema, then you should also update the schema documentation by the process described above.
284+
276285
### Running Queries with talawa-api
277286
278287
- Talawa API currently implement `GraphQL Playground` as mediator interface to run and test queries directly from the api. [Learn more](https://www.apollographql.com/docs/apollo-server/v2/testing/graphql-playground/)

‎docs/README.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Documentation
2+
3+
This directory contain the all the relevant documentation about the API for the developers.
4+
5+
Currently it has only one:
6+
7+
- [Schema.md](./Schema.md): Contains the documentation about the GraphQL schema in Markdown format. Auto-generated on push to `develop` branch with the help of `graphql-markdown` plugin.

0 commit comments

Comments
 (0)