add content related folders & changelog folders as git submodules

[devopstoday11]

@tfsumon ,
After finishing the versioning change task, I need this to be done. Or, if it is quick steps to add in config.toml, let me know what to do, I will do it myself.

Assuming you finished the versioning task...
This is what I am planning to do to handle the Topics' related folders from outside the docs repo.

I want to create separate git repos for documentation purposes for the Topics "compage , capten , kubviz , genval". In those independent repos, we will write & submit all the documentation.
Now, in our main docs repo (external-docs) , I want to add those independent repos as git submodules.

separate repos -

https://github.com/intelops/compage-docs
https://github.com/intelops/capten-docs
https://github.com/intelops/kubviz-docs
https://github.com/intelops/genval-docs
https://github.com/intelops/compage-changelog
https://github.com/intelops/capten-changelog
https://github.com/intelops/kubviz-changelog
https://github.com/intelops/genval-changelog

After adding them as git submodules to the main docs repo "external-docs" , the folder names should still be same as original names in this main repo. No need to change names. This means we don't want to change anything in this main docs repo.

content/compage
content/capten
content/kubviz
content/genval
content/changelog/capten
content/changelog/compage
content/changelog/kubviz
content/changelog/genval

Please let me know if you understand the requirements or have any questions. @tfsumon

[tfsumon]

This task may require some time and I will handle it.

To begin, please create all topics and changelog repositories based on the current file structure, as illustrated below. Once done, kindly notify me:

changelog >
compage >
version_number

compage >
version_number

[devopstoday11]

Ok. We can work on this later. I will try one idea I have first and then I'll let you know when to start working on this one. @tfsumon
Thanks for prompt response

[devopstoday11]

This task may require some time and I will handle it.

To begin, please create all topics and changelog repositories based on the current file structure, as illustrated below. Once done, kindly notify me:

changelog > compage > version_number

compage > version_number

@tfsumon , I created separate repos like this

https://github.com/intelops/compage-docs/
https://github.com/intelops/compage-changelog/

I created like that for all the topics.

https://github.com/orgs/intelops/repositories?q=docs&type=all&language=&sort=
In this search page, you will find newly created repos I created with the topicname-docs and topicname-changelog as repo names. All those repos are empty for now.

[tfsumon]

All those repos are empty for now.

Kindly add data on those repo so that I can incorporate them as submodules. Submodules won't serve their purpose without any data.

@devopstoday11

[devopstoday11]

All those repos are empty for now.

Kindly add data on those repo so that I can incorporate them as submodules. Submodules won't serve their purpose without any data.

@devopstoday11

What should be the folders in those repos? @tfsumon
Give me some examples please.

[tfsumon]

Take a look at the following repository. I've added 'compage' 'capten' changelog & docs as submodules. Let me know if you'd like something similar or if you have other preferences.

https://github.com/tfsumon/sub-external-docs

@devopstoday11

Clone the repository with the following command to include all its submodule files and folders:

git clone --recursive https://github.com/tfsumon/sub-external-docs.git

[devopstoday11]

Take a look at the following repository. I've added 'compage' 'capten' changelog & docs as submodules. Let me know if you'd like something similar or if you have other preferences.

https://github.com/tfsumon/sub-external-docs

@devopstoday11

Clone the repository with the following command to include all its submodule files and folders:

git clone --recursive https://github.com/tfsumon/sub-external-docs.git

Yeah I got the idea now.

One more idea I would like to discuss with you :

can I keep both docs and changelog of a topic in same repo (new separate repo) and still be able to add it as submodules to the correct paths we want into the main docs site repo? @tfsumon

[tfsumon]

It's not possible to achieve that. Currently, all changelogs in the main repository are situated inside the 'changelog' folder, and topics are within the 'content' folder. Git submodules do not provide an option to include a specific repository folder in a particular location.

But it is possible if you organize all topic changelogs inside the 'content' folder instead of the 'changelog' folder.

@devopstoday11

[devopstoday11]

But it is possible if you organize all topic changelogs inside the 'content' folder instead of the 'changelog' folder.

could you please show me what you meant exactly? I didn't get it.
give me example folder structure in this message how to organize the folders. That will be easy to understand. @tfsumon

[devopstoday11]

@tfsumon

one more idea to discuss,

In the separate repos if I do this -
In compage-docs repo
compage/version-number
changelog/version-number

can we get those into the main docs site repo as submodules into the content/compage?
content/compage/version-number
content/compage/changelog/version-number
OR
content/compage/version-number/docs
content/compage/version-number/changelog

Based on this we can modify those other separated repo (compage-docs repo) structure.

And in the live docs site, the user interactions should still be same, no change in UI interaction.
@tfsumon

[tfsumon]

But it is possible if you organize all topic changelogs inside the 'content' folder instead of the 'changelog' folder.

could you please show me what you meant exactly? I didn't get it. give me example folder structure in this message how to organize the folders. That will be easy to understand. @tfsumon

Current folder structure:

1. content/compage
2. content/changelog/compage

If you reorganize the topics into the following structure, you can consolidate changelog and docs for topic into the same repository:

1. content/compage
2. content/compage-changelog

@devopstoday11

[devopstoday11]

If you reorganize the topics into the following structure, you can consolidate changelog and docs for topic into the same repository:

1. content/compage
2. content/compage-changelog

So the new structure in the main docs site repo will be like this ?

content/compage/version-number
content/compage-changelog/version-number

@tfsumon

[tfsumon]

Exactly. Tell me if you're okay with this.

[devopstoday11]

@tfsumon with that new structure, there will not be any impact on the UI interaction right? still the flow will be same, correct?

and, what will be the structure of the folders in the separately consolidated repo ? @tfsumon

[tfsumon]

Correct. But, when you click the 'changelog' button in the header, it will take you to a specific topic's changelog page rather than the root page for all topics.

separately consolidated repo should have the following folders in the root:

1. compage
2. compage-changelog

@devopstoday11

[devopstoday11]

Correct. But, when you click the 'changelog' button in the header, it will take you to a specific topic's changelog page rather than the root page for all topics.

separately consolidated repo should have the following folders in the root:

1. compage
2. compage-changelog

@devopstoday11

Please proceed with this implementation with this new structure.

we already have topics' structure in place.
Now, you just have to structure the changelog folders and then show me a sample on how to use the separately consolidated repo , correct? @tfsumon

[tfsumon]

Before I proceed, could you set up the repository that will be added as a submodule in the main repository? I'm creating a sample repository for 'compage' using my GitHub account. Similarly, please create separate repositories for all other topics, including compage, using your GitHub account.

sample repo for compage - https://github.com/tfsumon/compage

@devopstoday11

When you've completed it, please lmk.

[devopstoday11]

Before I proceed, could you set up the repository that will be added as a submodule in the main repository? I'm creating a sample repository for 'compage' using my GitHub account. Similarly, please create separate repositories for all other topics, including compage, using your GitHub account.

sample repo for compage - https://github.com/tfsumon/compage

@devopstoday11

When you've completed it, please lmk.

I already created separate repos right -

for example, https://github.com/intelops/compage-docs/
for all our projects I did create the repos like this - https://github.com/intelops/<projectname>-docs/
We can use them.
The other extra repos I have currently, I can delete them.
This is the structure of extra repos - https://github.com/intelops/<projectname>-changelog/ , which I will delete.

[tfsumon]

In your created repositories, there are currently no folders. Kindly consider adding following folders to each of your separate repositories.

<topic>
<compage>-changelog

@devopstoday11

[devopstoday11]

@tfsumon ,
please try with this sample for now and let me know if it's working or not -

https://github.com/intelops/compage-docs/tree/chandu

[tfsumon]

Hello @devopstoday11!

Unfortunately, the current website structure with submodules isn't working. We need to make some changes:

Possible Scenario:

1. compage-docs submodule will be added to the main repo's content folder as compage.
2. compage-changelog submodule will also be added to the main repo's content folder as compage-changelog.

Not Possible Scenario based on earlier discussed structure:

1. compage-docs submodule containing both docs and changelog folders. Directly adding this submodule's content inside the content folder isn't possible without creating a folder inside content with a custom name or submodule name.

In this case, your main repo structure will look like:

• content/<submodule or custom name>/compage
• content/<submodule or custom name>/compage-changelog

If you want to keep both docs and changelog inside a single submodule, the main repo's structure will look like the second scenario I mentioned earlier. However, this structure might be challenging to work with given our current website flow. Let me know your preference. If separating them into two submodules works for you, we can follow the first scenario.

[devopstoday11]

@tfsumon ,
How about we structure like this?

the separate submodule related repo, for example -
compage-docs repo will have folders structure like this
compage/<version-number>/<document-folders>
in the same folder changelog will also be there like this
` compage//changelog/

In the docs site main repo -
content/compage - here compage folder is submodule

So now in the docs site UI when user visits the site, the user will be able to see the changelog content under the documentation section and also separately under the changelog section as well. For both sections data display would be coming from same changelog folder. I assume here you probably need to develop the new flow for the docs site, correct? @tfsumon

[tfsumon]

I assume here you probably need to develop the new flow for the docs site, correct?

Yeah. It won't take long since I've organized the code to easily modify the website flow whenever needed. So, your Git submodule repository structure will look like this:

Please tell me if I should go ahead with this.

@devopstoday11

[devopstoday11]

I assume here you probably need to develop the new flow for the docs site, correct?

Yeah. It won't take long since I've organized the code to easily modify the website flow whenever needed. So, your Git submodule repository structure will look like this:

Please tell me if I should go ahead with this.

@devopstoday11

yes please proceed @tfsumon

[tfsumon]

Hi @devopstoday11,

Could you kindly reorganize the repository folders according to the latest structure? Meanwhile, I'm actively working on developing the new flow for the documentation site.

[devopstoday11]

Hi @devopstoday11,

Could you kindly reorganize the repository folders according to the latest structure? Meanwhile, I'm actively working on developing the new flow for the documentation site.

@tfsumon ,
updated the repo - https://github.com/intelops/compage-docs/tree/chandu

[devopstoday11]

@tfsumon , any updates?

[tfsumon]

@devopstoday11

Working on new flow—it's a bit tougher than expected. Hoping to wrap it up by tomorrow.

[tfsumon]

Hi @devopstoday11,

I apologize for the delay in completing the task. I encountered unexpected challenges, and I need one more day to ensure the quality of the work. I appreciate your understanding and patience.

Can you organize your Git submodule like this: https://github.com/tfsumon/compage-docs/tree/chandu? You can add a .md file, but it's recommended to avoid any extra files or folders.

For the changelog, visiting "siteurl.com/changelog" will display all changelogs (Like following image).

Clicking a changelog link will lead to a detailed page. (Like following image)

is it correct?

[devopstoday11]

Hi @devopstoday11,

I apologize for the delay in completing the task. I encountered unexpected challenges, and I need one more day to ensure the quality of the work. I appreciate your understanding and patience.

Can you organize your Git submodule like this: https://github.com/tfsumon/compage-docs/tree/chandu? You can add a .md file, but it's recommended to avoid any extra files or folders.

For the changelog, visiting "siteurl.com/changelog" will display all changelogs (Like following image).

Clicking a changelog link will lead to a detailed page. (Like following image)

is it correct?

I'm confused about Git submodule organizing. Is the newly organized folder structure good or are you telling me to reorganize it differently? Please explain little bit more @tfsumon

The screenshots you mentioned looks fine.

[devopstoday11]

@tfsumon , pushed the restructured folders to the repo - https://github.com/intelops/compage-docs/tree/chandu

[tfsumon]

Thanks! I'll add this repo as git sub module and create a pull request once everything is finalized on my end.

[devopstoday11]

@tfsumon , done with this and also the URL Issue I mentioned on discord?

[tfsumon]

No, I've fixed the URL issue. I encountered an issue while testing. I'm in the process of fixing it, and once it's resolved, I'll create a pull request.

@devopstoday11