#1932 Publish v13 Docs using mike

[srikant-ch5]

Fixes: #1932 , #1895

Developer's Certificate of Origin 1.1

   By making a contribution to this project, I certify that:

   (a) The contribution was created in whole or in part by me and I
       have the right to submit it under the Apache License 2.0; or

   (b) The contribution is based upon previous work that, to the best
       of my knowledge, is covered under an appropriate open source
       license and I have the right under that license to submit that
       work with modifications, whether created in whole or in part
       by me, under the same open source license (unless I am
       permitted to submit under a different license), as indicated
       in the file; or

   (c) The contribution was provided directly to me by some other
       person who certified (a), (b) or (c) and I have not modified
       it.

   (d) I understand and agree that this project and the contribution
       are public and that a record of the contribution (including all
       personal information I submit with it, including my sign-off) is
       maintained indefinitely and may be redistributed consistent with
       this project or the open source license(s) involved.

[tomlyn]

I made this comment elsewhere but it seems to have disappeared: Previously we had to check with our release manager (Anita Chiu) if it was OK to introduce a new package into Elyra Canvas. Have you mentioned this to Anita?

[tomlyn]

Also, the README will need to be updated with new instructions on what to run -- just like we did when mkdocs was introduced.

[srikant-ch5]

Also, the README will need to be updated with new instructions on what to run -- just like we did when mkdocs was introduced.

Hi @tomlyn I have updated README and we have also got approval from Anita Chiu on slack.

[tomlyn]

This looks good to me. My only thought is can we style the dropdown to have a black background?

I think we should also get @matthoward366 's approval before merging it in.

Matt, are you OK with this? I'm am still a little unsure how we are going to use this. It's no use to switch between v12 and v13 and it might be a very long time before we go to v14 so are we going to add a new entry to the drop down for every minor release of v13 (v13.1, v13.2, etc) ?

Tagging @JesusGuerrero in case he has some input.

[matthoward366]

We wouldn't have doc versions for each minor release.

I'm curious how this works in the future. When we do create a 14 version are there changes need in both 13 and 14 branches to make this work?

[srikant-ch5]

When we do create a 14 version are there changes need in both 13 and 14 branches to make this work?

Hi @matthoward366 When we create 14 version then only changes to one branch is enough. Only thing we need to change is in deploy-docs.yml file update run: mike deploy to v14 which will deploy all the changes in docs folder to a separate folder in gh-pages and similarly need to create a separate folder for v13

@tomlyn I have updated docs to include dropdown with black background.

[matthoward366]

similarly need to create a separate folder for v13

Would this be on main or the v13 branch? If we make changes in the v13 branch will that update the documentation?

[matthoward366]

What is this for?

[srikant-ch5]

This is to create initial setup in gh-pages which will create a folder named v12.x and place all the doc changes in it. So when we select on v12.x from dropdown it will fetch docs from this folder.

[matthoward366]

Since we won't have v12 docs should this be removed?

[srikant-ch5]

Yes this can be removed if there is no v12 docs. Should I remove this ?

[matthoward366]

Yes, I think we should. @tomlyn do you agree?

[srikant-ch5]

Sure. I have removed that from Readme.

[matthoward366]

It's still not clear to me how this is going to work for the different branches and how each branch documentation is going to maintained.

[srikant-ch5]

It's still not clear to me how this is going to work for the different branches and how each branch documentation is going to maintained.

@matthoward366 If we want to use mkdocs versioning for different branches we must have changes from this PR in all the branches with mike deploy command consisting branch name.

[matthoward366]

When we create a new v13 branch can you give me the steps needed?
What changes are needed on main and v13?
If we make a change in the v13 docs how does that work?

[srikant-ch5]

When we create a new v13 branch can you give me the steps needed? What changes are needed on main and v13? If we make a change in the v13 docs how does that work?

-If there is a new v13 branch which is derived from current main then no changes are needed in it as current main branch will already have deploy-docs.yml deploy command as mike deploy --push --update-aliases v13.

-Changes should be made in main branch (v14) by updating deploy-docs.yml file as mike deploy --push --update-aliases v14 latest. Here we have changed latest to v14.

so https://elyra-ai.github.io/canvas/v14 and https://elyra-ai.github.io/canvas/latest will navigate to same v14 docs.

[tomlyn]

Hi @srikant-ch5
I noticed that with mike serve running I am no longer able to edit a .md file and then see the changes immediately reflected in the browser like I was able to do when running mkdocs serve. Is that a restriction with mike? If so it might be worth mentioning in the readme that developers working on the docs should just run mkdocs serve.

[srikant-ch5]

Hi @srikant-ch5 I noticed that with mike serve running I am no longer able to edit a .md file and then see the changes immediately reflected in the browser like I was able to do when running mkdocs serve. Is that a restriction with mike? If so it might be worth mentioning in the readme that developers working on the docs should just run mkdocs serve.

Hi @tomlyn I have updated readme with mkdocs serve command.

[tomlyn]

Can you write this as: "If you are working on Elyra Canvas documentation content, you should run the following command, instead of the mike serve command, to see your changes immediately reflected in the browser."

[srikant-ch5]

Sure, I have updated accordingly.

[srikant-ch5]

Hi @tomlyn any update on this PR, any changes needs to be done here ?

[tomlyn]

@srikant-ch5 It looks good to me but I think we should wait until @matthoward366 is happy. He is currently away and back on Tuesday June 4th.

[matthoward366]

lgtm

[tomlyn]

LGTM