Add auto schema markdown generation to Talawa-API [Fixes part of Pali…

…sadoesFoundation#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]>

.eslintignore

@@ -3,4 +3,5 @@
 build
 coverage
 node_modules
-src/types
+src/types
+docs/Schema.md

.github/workflows/push.yml

@@ -25,8 +25,8 @@ jobs:
   # code coverage (post PR merge) is reported
   ##############################################################################
 
-  Test-Application:
-    name: Testing Application
+  Push-Workflow:
+    name: Testing Application and Updating Documentation
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -46,9 +46,13 @@ jobs:
       ACCESS_TOKEN_SECRET: ${{ secrets.ACCESS_TOKEN_SECRET }}
       REFRESH_TOKEN_SECRET: ${{ secrets.REFRESH_TOKEN_SECRET }}
 
+    # We checkout the content of the Talawa-API repository in a directory called `api`
+    # This is done as we will use the Talawa-Docs repository later too
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
+        with:
+          path: api
 
       - name: Generate Access Token Secret
         run: echo "ACCESS_TOKEN_SECRET=$(openssl rand -hex 32)" >> $GITHUB_ENV
@@ -59,20 +63,75 @@ jobs:
       - name: Set up Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v3
 
+      # Move into the api folder before installing the dependencies
       - name: Install dependencies
-        run: npm ci
+        run: cd api && npm ci
 
+      # Move into the api folder before starting the server
+      - name: Start the development server in detach mode
+        run: |
+          cd api && npm run dev &
+          echo "Development server started..."
       - name: Sleep for 10s
         uses: juliangruber/sleep-action@v1
         with:
           time: 10s
 
+      # Move into the api folder before generating the Markdown schema documentation
+      - name: Generate the GraphQL-Markdown documentation
+        run: cd api && npm run generate:graphql-markdown
+
+      # Move into the api folder before generating the Schema is json form
+      - name: Genrate the GraphQL Schema in JSON form
+        run: cd api && npm run generate:graphql-schema
+
+
+      # Running the generate::** scripts will create the necessary documentation on the server 
+      # where the GitHub Action is running locally. We add the same to stage with -f flag as they are a 
+      # part of the .gitignore file
+      - name: Add the generated Markdown Documentation to stage
+        run: cd api && git add docs/Schema.md -f
+
+      # We use this action to commit the changes above to the repository
+      - name: Commit generated Markdown Documentation to the Talawa API repository
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: Generate GraphQL Schema and Markdown Documentation
+          repository: api
+
+      # We will clone the Talawa Docs in the folder called docs so that we can copy the generated
+      # schema.json into the same later
+      - name: Checkout the Talawa-Docs repository
+        uses: actions/checkout@v3
+        with:
+          repository: PalisadoesFoundation/talawa-docs
+          token: ${{ secrets.TALAWA_DOCS_SYNC }}
+          path: docs
+
+      # Copy the generated schema.json into the Talawa Docs repository 
+      - name: Sync schema.json from Talawa API to Talawa Docs
+        run: cp api/docs/schema.json docs/docs/
+
+      # Add the updated schema.json in Talawa Docs to stage
+      - name: Add the synced schema.json to stage in Talawa Docs
+        run: cd docs && git add docs/schema.json
+
+      # Commit the changes made to schema.json into Talawa Docs
+      - name: Commit the synced schema to the Talawa Docs repository
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: Update schema.json
+          repository: docs
+
+      # Testing the application after moving into the api folder
       - name: Run the tests
-        run: npm run test
+        run: cd api && npm run test
 
+      # Upload Coverage
       - name: Present and upload coverage to Codecov as ${{env.CODECOV_UNIQUE_NAME}}
         uses: codecov/codecov-action@v3
         with:
+          directory: api
           verbose: true
           fail_ci_if_error: false
-          name: '${{env.CODECOV_UNIQUE_NAME}}'  
+          name: '${{env.CODECOV_UNIQUE_NAME}}'  

.gitignore

@@ -1,3 +1,7 @@
+# Add the auto-generated docs to .gitignore as the same are created by GitHub actions
+docs/Schema.md
+docs/schema.json
+
 node_modules
 .idea
 .env

.husky/pre-commit

@@ -1,4 +1,9 @@
 #!/usr/bin/env sh
+
+# Disable the hooks in CI 
+[ -n "$CI" ] && exit 0
+
+# Change to the current directory
 . "$(dirname -- "$0")/_/husky.sh"
 
 # Formats code using prettier.
@@ -10,3 +15,6 @@ npm run typecheck
 # Checks and fixes all lint issues in code which don't require manual intervention.
 # Throws errors if lint issues requiring manual intervention are found in code.
 npm run lint:fix
+
+# Add the changes made to the stage
+git add .

.prettierignore

@@ -3,4 +3,5 @@
 build
 coverage
 node_modules
-src/types
+src/types
+docs/Schema.md

CONTRIBUTING.md

@@ -27,6 +27,7 @@ If you are new to contributing to open source, please read the Open Source Guide
       - [Pre-Commit hook](#pre-commit-hook)
       - [Post-Merge hook](#post-merge-hook)
     - [GraphQL Voyager](#graphql-voyager)
+    - [GraphQL Markdown](#graphql-markdown)
     - [Running Queries with talawa-api](#running-queries-with-talawa-api)
   - [Internships](#internships)
   - [Community](#community)
@@ -273,6 +274,14 @@ Go to `http://localhost:4000/voyager` after running the development server to ex
 
 ![Voyager Demo for User Model](./image/GraphQL_Voyager.png)
 
+### GraphQL Markdown
+
+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`.
+
+You can then view the [generated documentation here](./docs/Schema.md).
+
+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.
+
 ### Running Queries with talawa-api
 
 - 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

@@ -0,0 +1,7 @@
+# Documentation
+
+This directory contain the all the relevant documentation about the API for the developers.
+
+Currently it has only one:
+
+- [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.