Add automatic documentation of the API Schema [Fixes #629]

[EshaanAgg]

What kind of change does this PR introduce? Feature

Issue Number:

Fixes #629

Did you add tests for your changes? NA

Snapshots/Videos: NA

If relevant, did you update the documentation? NA

Summary Now the schema will be updated for the repository automatically whenever the schema.json file is changed from the Talawa API's github action.

Does this PR introduce a breaking change? No

Other information NA

Have you read the contributing guide? Yes

[github-actions[bot]]

Our Pull Request Approval Process

We have these basic policies to make the approval process smoother for our volunteer team.

Testing Your Code

Please make sure your code passes all tests and there are no merge conflicts.

The process helps maintain accurate and well-formatted documentation and is a prerequisite for getting your PR approved. Assigned reviewers regularly review the PR queue and tend to focus on PRs that are passing.

Reviewers

When your PR has been assigned reviewers contact them to get your code reviewed and approved via:

1. comments in this PR or
2. our slack channel

Reviewing Your Code

Your reviewer(s) will have the following roles:

1. arbitrators of future discussions with other contributors about the validity of your changes
2. point of contact for evaluating the validity of your work
3. person who verifies matching issues by others that should be closed.
4. person who gives general guidance in fixing your tests

CONTRIBUTING.md

Read our CONTRIBUTING.md file. Most importantly:

1. PRs with issues not assigned to you will be closed by the reviewer
2. Fix the first comment in the PR so that each issue listed automatically closes

Other

1. :dart: Please be considerate of our volunteers' time. Contacting the person who assigned the reviewers is not advised unless they ask for your input. Do not @ the person who did the assignment otherwise.

[EshaanAgg]

1. Can you elaborate on this webserver thing? Locally, I can access them. Clicking schema documentation tab opens the generated pages.

2. I had updated the sidebars.js to include a new sidebar.

[palisadoes]

1. I was expecting it to be added to the sidebar under docs.
2. It's not an intuitive location where it is now.
3. The docs links from the other repos will need to eventually be moved from the nav bar too. The reason for this is that every new integration will be on the NavBar and we'll run out of space.
4. It is not intuitive either. For example, we now have two links in the NavBar for the API. One for the modules and another for the schema.

How can this be content be added under the existing sidebar? There must be a way to do this.

[EshaanAgg]

I'm not sure how can we do the same. Currently, all the sidebars and their values are added manually to the file sidebars.js. But the whole point of using the plugin so that we do not have to generate anything ourselves. Even in the documentation of the plugin, there is no section about integrating it with already existing sidebar (except for the import that I have already done)

I'll read about it a bit more never the less.

[palisadoes]

I'm not sure how can we do the same. Currently, all the sidebars and their values are added manually to the file sidebars.js. But the whole point of using the plugin so that we do not have to generate anything ourselves. Even in the documentation of the plugin, there is no section about integrating it with already existing sidebar (except for the import that I have already done)

I'll read about it a bit more never the less.

There must be a way where we can:

1. add a single manual entry into the sidebar which then links to docs/schema. We already have an entry for schemas here which could be replaced:
   1. http://localhost:3000/docs/developers/talawa-api/schemas
2. remove the current NavBar entry

That way we have a more logical flow.

I have noticed that the automated schema content is not as good as the manually created one which has more context.

1. Automated: http://localhost:3000/docs/schema/queries/posts
2. Manual: http://localhost:3000/docs/developers/talawa-api/schemas

Additional questions:

1. Is there a way where the schema.json file can include comments from the original source code for things like the arguments and queries?
2. How can we get all the links to work in the new automated schema? For example in the case above for http://localhost:3000/docs/schema/queries/posts, you get 404 errors when you click on:
   1. PostOrderByInput
   2. Post

[EshaanAgg]

Got it @palisadoes. I would try to work on all of the questions and suggestions you have posted above, and come up with an answer ASAP.

[EshaanAgg]

@palisadoes As you can see in this PR, the test-deploy job is working correctly, as the same doesn't have the latest changes pulled from the talawa automatic documentation updation. Thus we can safely say that it's not the recently added Talawa API job that is causing the deployment to fail here in the docs.

You may consider closing this issue as the same in not the cause of the problem as far as I can understand.

[EshaanAgg]

@palisadoes

1. I have added an entry for the same in the sidebar in the API section, and removed it from the main navbar.
2. The schema.json file already has the descriptions for some fields that has comments describing their purpose in the typeDefs in Talawa-API. You can make it as a project for potential GSoD candidates to add comments to the typeDefs describing the use of each type. Then the same would be automatically reflected in the documentation here.
3. I have fixed the links which were not working earlier.
4. The automated content would never be as good as the manually created content for obvious reasons. But I guess it's a tradeoff that we have to make, as we want all of out code to be documented and not such some parts of it.

[EshaanAgg]

@palisadoes Can you please review the PR as is? I would fix the conflicts later after your approval, as as soon as I pull changes from the develop branch, even the test-deploy job would start to fail for this PR due to the introduction of improperly named files in the recent merges.

[palisadoes]

Please fix the conflicts

[EshaanAgg]

@palisadoes Done.

[palisadoes]

@EshaanAgg @literalEval How can we fix the GitHub Pages deployment error?

[literalEval]

@palisadoes I researched a bit about it and the some ideas refer to adding some sort of numbering or hash to the file name, so that they can never be same as each other. But Dart Doc doesn't not seem to support this. I have raised an issue regarding this on their repo though.

A temporary fix, as I said before, can be to rename the field from message to messageStr maybe will generate files with different names.

[palisadoes]

1. Rename it if required and create a PR.
2. Make sure it doesn't break the code elsewhere.

[EshaanAgg]

@literalEval Wouldn't renaming things require all the hyperlinks to the same automated as well? Does Dart Doc support the same?

[literalEval]

@EshaanAgg that's exactly what I am discussing with the DartDoc maintainers.

[EshaanAgg]

@palisadoes Please review.

[palisadoes]

Please fix the conflicts

[palisadoes]

@EshaanAgg The push run failed. Please troubleshoot this

• https://github.com/PalisadoesFoundation/talawa-docs/actions/runs/4710652445

[EshaanAgg]

@palisadoes Opened a fixing PR #639