Description

• This PR introduces an automated workflow to push community files onto the website.
• We can have several other PRs which modifies the structure of the docs present on this repo if required.
• Bringing your kind attention on this PR and corresponding issue @alequetzalli @TRohit20 @akshatnema @derberg @sambhavgupta0705 @anshgoyalevil

Related issue(s)

Resolves #1028 Resolves #773

https://github.com/asyncapi/extensions-catalog/blob/master/.github%2Fworkflows%2Fupdate-extensions-in-website.yml Take inspiration from this file

https://github.com/asyncapi/extensions-catalog/blob/master/.github%2Fworkflows%2Fupdate-extensions-in-website.yml Take inspiration from this file

I'll take a look at it :+1: @sambhavgupta0705

---

btw, have a look at the following PR which is of similar nature and was used to push Glee docs to website:

• https://github.com/asyncapi/glee/pull/548

I took initial reference from here. Can you please explain me what's the difference between Lukasz's reference and your reference?

btw, have a look at the following PR which is of similar nature and was used to push Glee docs to website:

• ci: glee docs automation workflow glee#548

I took initial reference from here. Can you please explain me what's the difference between Lukasz's reference and your reference?

the workflow I shared directly adds the link of the community to the edit-on-github.json config file

we need to see if we need the increment of weights workflow for this workflow

btw, have a look at the following PR which is of similar nature and was used to push Glee docs to website:

• ci: glee docs automation workflow glee#548

I took initial reference from here. Can you please explain me what's the difference between Lukasz's reference and your reference?

the workflow I shared directly adds the link of the community to the edit-on-github.json config file

Got it. Let me work on that...

@AnimeshKumar923 From what I understand the PR is setting up a workflow such that, on push to community docs in the community repo, we want the changes to sync on the website(website repo) which means the workflow should create a PR and get auto-merged.

I have already worked on similar automation workflow previously, you can check out the workflow here for reference.

cc @sambhavgupta0705 @alequetzalli

Thanks for the reference! :+1: @TRohit20

/au

also, what docs will we be pushing onto the website? @alequetzalli @TRohit20 I assume the onboarding-guide will definitely be pushed as far as I know... What else? Can we have a list of it?

I'd suggest not to hard code the files we'd push on, use paths instead. Makes your file easier haha

Question, @AnimeshKumar923, is this PR to replace the one I tried to make via https://github.com/asyncapi/community/pull/1064? I don't mind at all, if that is the case, I honestly still don't understand fully how to automate pushing our community docs to the website. If someone else such as yourself is making a PR to show me how to do so, please do share. 😅

Also, sorry but I do not fully understand the code. Can you walk me through it more? 🙏🏻 cc @TRohit20

Question, @AnimeshKumar923, is this PR to replace the one I tried to make via #1064? I don't mind at all, if that is the case, I honestly still don't understand fully how to automate pushing our community docs to the website. If someone else such as yourself is making a PR to show me how to do so, please do share. 😅

Also, sorry but I do not fully understand the code. Can you walk me through it more? 🙏🏻 cc @TRohit20

Hey @alequetzalli sorry about that. I didn't see that PR as it wasn't linked in the original issue, hence I missed #1064 :sweat_smile:

If it's fine with you, I can help with the community docs automation through this PR. :grin:

@alequetzalli (DISCLAIMER: I'll try my best to explain, although I'm still learning so please verify the explanation @sambhavgupta0705 @akshatnema)

Automation Workflow

• Whenever there's a docs PR on the master branch which is of .md type, the workflow gets triggered.

• Then there are number of jobs that takes place.

• Make-PR gets executed. Inside this, there are further sub-jobs which takes place.

• It then checks out the specified repository (community repo here)

  steps:
    - name: Checkout Current repository
      uses: actions/checkout@v4
      with:
        path: community
  

• Then it checks out another repo (which is website repo here) using the following:

  name: Checkout Another repository
      uses: actions/checkout@v4
      with:
        repository: asyncapi/website
        path: website
        token: ${{ env.GITHUB_TOKEN }}
  

• After that, it configures the git

  name: Config git
      run: |
        git config --global user.name asyncapi-bot
        git config --global user.email [email protected]
  

• Then it creates a new branch with commit id

  name: Create branch
      working-directory: ./website
      run: |
        git checkout -b update-community-docs-${{ github.sha }}
  

• @sambhavgupta0705 please explain this part...

      name: Update edit-page-config.json
          uses: actions/github-script@v4
          with:
              script: |
              const { writeFile } = require('fs').promises;
              const configPath = './website/config/edit-page-config.json';
              const checkSlug = 'reference/extensions/';
              const slug = {
                  "value": checkSlug,
                  "href": "https://github.com/asyncapi/community/tree/master/docs"
              };
  
              const configData = require(configPath);
              const entryExists = configData.some(entry => entry.value === checkSlug);
              if (!entryExists) {
                  configData.push(slug);
                  await writeFile(configPath, JSON.stringify(configData, null, 2))
              }
      ```
  
  

• After that, it copies the specified files from community repo to the website repo

  name: Copy community folder from Current Repo to Another
      working-directory: ./website
      run: |
        mkdir -p ./pages/docs/community/
        printf "%s\ntitle: Community\nweight: 7\n%s" "---" "---"> ../community/docs/_section.md
        mv ../community/docs/*.md ./pages/docs/community
  

• After the files are copies, it commits and pushes the changes

  name: Commit and push
      working-directory: ./website
      run: |
        git add .
        git commit -m "docs(community): update latest community docs"
        git push https://${{ env.GITHUB_TOKEN }}@github.com/asyncapi/website
  

• At last, we create a PR with title docs(community): update latest community documentation with PR body being Updated community documentation is available and this PR introduces update to community folder on the website

  name: Create PR
      working-directory: ./website
      run: |
        gh pr create --title "docs(community): update latest community documentation" --body "Updated community documentation is available and this PR introduces update to community folder on the website" --head "update-community-docs-${{ github.sha }}"
  

@AnimeshKumar923 I will explain the whole workflow to you soon

NOTE: Sharing some notes that @KhudaDad414 shared with me via DM about this task in case it helps @AnimeshKumar923.

---

If I understood the issue correctly then this is how we approached it in glee:

• created this workflow in the glee project. https://github.com/asyncapi/glee/blob/master/.github/workflows/update-docs-in-website.yml
• adding a _section.md file in the Glee project here (https://github.com/asyncapi/glee/blob/master/docs/pages/_section.md)
• made sure all of the .md files can compile as we want them to by putting them in a local instance of the website.
• now any time we update the docs, website is going to be updated automatically.

Thank you for that extremely detailed walk-through of your code, @AnimeshKumar923!! I really appreciate it. 😀

also, what docs will we be pushing onto the website? I assume the onboarding-guide will definitely be pushed as far as I know... What else? Can we have a list of it?

Thank you, good question! We should push whatever is in the /docs directory, with the exception of the README. That leaves us with:

1. Onboarding Guide
2. How changes in spec are introduced

Does that make sense? lemme know ✌🏽

Thank you for that extremely detailed walk-through of your code, @AnimeshKumar923!! I really appreciate it. 😀

My pleasure! :grin:

also, what docs will we be pushing onto the website? I assume the onboarding-guide will definitely be pushed as far as I know... What else? Can we have a list of it?

Thank you, good question! We should push whatever is in the /docs directory, with the exception of the README. That leaves us with:

1. [Onboarding Guide](https://github.com/asyncapi/community/tree/master/docs/onboarding-guide)

2. [How changes in spec are introduced](https://github.com/asyncapi/community/blob/master/docs/how-changes-in-the-spec-are-introduced.md)

Does that make sense? lemme know ✌🏽

Yes, definitely. Thanks for the clarification! @alequetzalli

NOTE: Sharing some notes that @KhudaDad414 shared with me via DM about this task in case it helps @AnimeshKumar923.

If I understood the issue correctly then this is how we approached it in glee:

* created this workflow in the glee project. https://github.com/asyncapi/glee/blob/master/.github/workflows/update-docs-in-website.yml

* adding a _section.md file in the Glee project here (https://github.com/asyncapi/glee/blob/master/docs/pages/_section.md)

* made sure all of the .md files can compile as we want them to by putting them in a local instance of the website.

* now any time we update the docs, website is going to be updated automatically.

@alequetzalli

Thanks for sharing the notes. It will definitely help in the development process of this feature. :+1:

---

I think for the modification in the docs structure, we should have separate PRs for better management and reviews. cc: @TRohit20

@sambhavgupta0705 please explain this part...

name: Update edit-page-config.json
    uses: actions/github-script@v4
    with:
        script: |
        const { writeFile } = require('fs').promises;
        const configPath = './website/config/edit-page-config.json';
        const checkSlug = 'reference/extensions/';
        const slug = {
            "value": checkSlug,
            "href": "https://github.com/asyncapi/community/tree/master/docs"
        };
        
        const configData = require(configPath);
        const entryExists = configData.some(entry => entry.value === checkSlug);
        if (!entryExists) {
            configData.push(slug);
            await writeFile(configPath, JSON.stringify(configData, null, 2))
        }
```

@AnimeshKumar923 So here scripting is being done From L39 It is accessing the file website/config/edit-page-on-website file where the config file for edit page section button is present. Check slug checks the data of the file and if the slug of the file is not present then it will add the new slug otherwise it will leave it . slug is the url to which it will be redirected when the user clicks edit page on GitHub ` button

@AnimeshKumar923 if you have any other doubt then you may ask

See for this issue You just need to copy the workflow I made in extension catalogue and change the working url and slugs

@sambhavgupta0705

I haven't added the title and weight updating part of the workflow. I think we should specify which document should be displayed in which order.

cc: @alequetzalli

Yes you can remove that part I think

Yes you can remove that part I think

The markdown updating part? I haven't added that to this file, so I guess that's excluded for now

Yes you can remove that part I think

The markdown updating part? I haven't added that to this file, so I guess that's excluded for now

Yeaah the line which was adding the weight and title,you can remove that

@AnimeshKumar923 When it comes to the order to display these docs, we want the Technical Writer Onboarding Guide to go directly after the /Overview page, as you can see pointed here:

Since the Community /Overview page has a page weight of 2, any number greater than that should work.

Currently, the TW Onboarding Guide has a page weight of 10, so they can and should be merged as is.

p.s. The 'how spec changes are introduced' doc currently has no page weight, so that would need to be added.

Hey @alequetzalli, check out this test deployment here: https://deploy-preview-2767--asyncapi-website.netlify.app/docs/community Let me know is this how the docs are expected to be displayed.

@AnimeshKumar923 can you please provide the link from where this documentation is being taken up and the url point at which you want to place it just as this https://www.asyncapi.com/docs/concepts/server As it will give me better understanding and after that I will add my final review

@akshatnema @AnimeshKumar923 what should we do of readme.md file of the docs folder

@akshatnema @AnimeshKumar923 what should we do of readme.md file of the docs folder

@sambhavgupta0705 Checkout this comment by Alejandra: https://github.com/asyncapi/community/pull/1082#issuecomment-1982238178

Hey @alequetzalli, check out this test deployment here: https://deploy-preview-2767--asyncapi-website.netlify.app/docs/community Let me know is this how the docs are expected to be displayed.

@AnimeshKumar923 yep! that is correct! So will you open the PR to move those over or..? 👯