Automatically Update Talawa-Docs with the latest API Schema

[palisadoes]

Is your feature request related to a problem? Please describe.
The API GraphQL schema is constantly changing and it is difficult to manually document it for all the developers who need to use it in the following repos:

1. Talawa
2. Talawa-API
3. Talawa-Admin

Describe the solution you'd like
We have identified an open source project that can convert schema files, or query a GraphQL url, to generate a markdown file containing all the elements of the schema using whatever comments the developers have added to the schema definitions.

• https://github.com/exogen/graphql-markdown

We would like to:

1. use this software to automatically add the latest schema to the appropriate file in Talawa Docs with every post PR push
2. keep the generator code within the Talawa-API repo in a directory tree reserved for GitHub automation (if advisable)

Describe alternatives you've considered

N/A

Approach to be followed (optional)

See above

Additional context

1. The https://github.com/exogen/graphql-markdown installation is incorrect.
2. The build process creates a src/index.js file which the documentation refers to as the graphql-markdown executable.

[palisadoes]

@tasneemkoushar, @anwersayeed and @evasharma12 this should be interesting to you.

[EshaanAgg]

I would like to work on this issue @palisadoes.

[anwersayeed]

I would like to work on this issue @palisadoes.

SpectaQL, you may try this library too.

[palisadoes]

@EshaanAgg

You may want to work on this one simultaneously

• Generate image of GraphQL schema with each PR #1244

[palisadoes]

I would like to work on this issue @palisadoes.

SpectaQL, you may try this library too.

This format looks better.

@EshaanAgg try both and let us know which one you think gives a more readable output

[EshaanAgg]

@palisadoes @anwersayeed
The problem that I am facing while using both of the tools is that they need the .graphql file of the schema to generate the documentation automatically.

They can do the same themselves, but with some caveats:

1. We can provide them with the URL of the hosted API service, and then they would use Introspection queries to generate the same. The same is not possible for us as we do not host the API anywhere.
2. We can provide them with the schema in .json or .gql files, but the same isn't generated by us as of now(or I am not aware of the same). Thus even this option goes out of the window for us.

If someone with some prior experience can help me in the same, I would greatly appreciate it.

[EshaanAgg]

@palisadoes
Can we consider hosting the API online? That way we can directly make a cron job in the Talawa-Docs repository to fetch the GraphQL schema from the hosted API, and update the same if any schema definitions have changed.
We have a hosted API URL linked to the repository, but I don't think so the same is functional any more.

[anshgoyalevil]

@palisadoes @EshaanAgg

We would be integrating Squash CI, which would orchestrate a development server with each PR, and thus we can generate the Schema using that server's link

[palisadoes]

Can this be used with a simplified installation process for GitHub?

• https://github.com/marketplace/actions/mongodb-in-github-actions

[anshgoyalevil]

@palisadoes

I guess this can be used too. @EshaanAgg Check out this supercharge/mongodb-github-action#24 if you face any error while connecting to URL.

[EshaanAgg]

@palisadoes @anshgoyalevil
The problem isn't starting a MongoDB container, it's running the server and executing the Markdown Generator script parallely. Because after we run the 'npm run dev' command, the terminal would be engaged in the same process.

One prospective way of doing so may be using a docker image and exposing a development container via the same in the GitHub action.

[anshgoyalevil]

@EshaanAgg I think we can run npm run dev command in detached mode with a workaround in linux. Moreover, having a docker image is always a good idea for a multi-repo based application, but that would then include creating the docker images everytime a PR is created, then instantiating a container. Shouldn't we use other CI tools for all that, like Jenkins.

[palisadoes]

GitHub actions allows you to create jobs in which you can make one job dependent on another. We had that before for the API workflow:

• https://docs.github.com/en/actions/using-jobs/using-jobs-in-a-workflow

Docker example:

• https://thetechdarts.com/setup-mongodb-database-in-github-actions-workflow/

We have a limited number of minutes (2000) per month for GitHub actions. Ideally we will want to do this on the push when the PR is merged.

[palisadoes]

@EshaanAgg @anwersayeed Which one do you think we should go with?

1. SpectaQL:
   1. is much more visually appealing and usable, though it outputs as HTML versus markdown.
   2. It uses frames so that the menu items on the left are always visible.
   3. It allows you to have a custom introduction at the top of the page obtained from a pre-defined markdown file.
   4. Has its own CSS. We'll need to find a way to override it for Talawa-Docs
   5. Has an embeddable mode where only the body HTML is generated, but the specific stylesheets are still created.
2. GraphQL Markdown:
   1. Will blend in better with our Docusaurus site as it doesn't have any custom CSS
   2. Doesn't have the customizations
   3. Allows you to have a custom introduction at the top of the page too.

SpectaQL

GraphQL Markdown

[palisadoes]

I've been playing around with this. If you put the SpectaQL output in an HTML iframe the rendering of the query strings becomes a single line of text that scrolls off the page versus what we see in the black sections above.

Let's stick with the Markdown solution, then we can figure out SpectaQL later.

[EshaanAgg]

I also advocate for GraphQL Markdown because of its simplicity and the fact that it generates a simple markdown file. It would be much easier to configure the same into Talawa Docs than a complete HTML file! SpectaQL has a nice look and feel, but introduces overhead that I don't think so we need right now.

[xoldd]

@palisadoes @EshaanAgg @anshgoyalevil This one's good too:-
https://magidoc.js.org/introduction/welcome

Graphql markdown looks good too.

[anshgoyalevil]

@xoldyckk

I checked Magidoc. The features like Example Query, Sidebar, etc looks good.

For it to work, custom scalers would need to be configured with queryGenerationFactories which could increase the implementation complexity.

[EshaanAgg]

I agree with @anshgoyalevil. While the look and feel of Magidoc is great, I feel it would be much easier to integrate GraphQL Markdown into both the workflows and Talawa Docs.

[palisadoes]

I just discovered this:

• https://graphql-markdown.github.io/ A GraphQL plugin for Docusaurus. It imports a schema.graphql file.
• This site shows you how to create the schema file using curl.

It automatically creates the required menu entries for each. Look at this:

• https://graphql-markdown.github.io/schema/schema

This looks like exactly what we need.