Feature Request : Documentation Automation: Bridging talawa-api and talawa-docs repositories

[tasneemkoushar]

The current approach to generating and synchronizing documentation between the talawa-api and talawa-docs repositories faces challenges related to branch protection rules and the specification of source and destination branches.

Current Workflow: talawa-api generates markdown files from inline tsdoc comments. These files are stored in a dedicated folder within the talawa-api repository. GitHub Actions encounters difficulties transferring these files to the talawa-docs repository, particularly due to some rules.

Challenges:

1. Branch Protection Rules: The develop branch in talawa-api is safeguarded, impeding direct commits.
2. Source and Destination Branch Specification: Complications arise in specifying source and destination branches for the documentation transfer.

Proposed Solution: Trigger the workflow on a schedule or in response to push events on the develop branch of talawa-api. Automate the generation of documentation files from inline comments (Already Implemented). Commit files directly to the specified branch and folder location in the talawa-docs repository.

Implementation Steps: Explore existing workflows for innovative insights and references. Fork the talawa-api and talawa-docs repository to kickstart the documentation automation. Conduct thorough local testing to validate the efficacy of the automation.

[gautam-divyanshu]

@tasneemkoushar @anwersayeed can we close this issue also if mechanism is changed?

[gautam-divyanshu]

@anwersayeed @tasneemkoushar @palisadoes Do I need to fix the cron job that was implemented in Docs?

[tasneemkoushar]

@gautam-divyanshu you don't need to do anything on this issue currently, It seems like @anwersayeed already fixed workflow issue of the talawa-api & talawa-admin, but I will keep this issue open for my observation period. The current cron job runs every Sunday, so for some more weeks I need to check if the automation.

I kind of missed out on the current flow but now I have documented the architecture and challenges. If you want to understand the current flow & the related challenge please refer here

[gautam-divyanshu]

@tasneemkoushar Okay, thanks for informing me.

I will try to run that locally to observe. I found an error in the generation of docs while I was working on my PR; that is deprecated code, and it is also present in the docs repo workflow.

and I will remove that.

[github-actions[bot]]

This issue did not get any activity in the past 10 days and will be closed in 180 days if no update occurs. Please check if the develop branch has fixed it and report again or close the issue.

[gautam-divyanshu]

@tasneemkoushar can we close this issue now?

[gautam-divyanshu]

@tasneemkoushar @anwersayeed I think cron job is working now,

[gautam-divyanshu]

you can see the changes here,

https://github.com/PalisadoesFoundation/talawa-docs/blob/develop/docs/talawa-api-docs/directives/directiveTransformer/authDirectiveTransformer/functions/default.md

[gautam-divyanshu]

docs websites is not updated because there is difference in folder structure

[gautam-divyanshu]

@palisadoes I will fix that later

[palisadoes]

@tasneemkoushar @anwersayeed PTAL

[tasneemkoushar]

@gautam-divyanshu I have check on few things, since I saw the workflow running and the folder getting updated. Would like to see the issue which you are facing. Let’s connect on slack

[gautam-divyanshu]

@tasneemkoushar This section is being generated.

[gautam-divyanshu]

The problem is with the sidebar. Because the folder structure has changed, we need to remove the sidebar from the API and admin documents.

[tasneemkoushar]

@gautam-divyanshu but we need sidebar

[gautam-divyanshu]

it is removed for api and admin section only, and sidebar is same for others

[github-actions[bot]]

This issue did not get any activity in the past 10 days and will be closed in 180 days if no update occurs. Please check if the develop branch has fixed it and report again or close the issue.