[Bug]: Fix and update doc deployment workflow

[danuw]

Contact Details

No response

What happened?

The following worklfow builds documentation that has not run for over a year.
https://github.com/Green-Software-Foundation/carbon-aware-sdk/actions/workflows/pages/pages-build-deployment

Do we need to fix so the latest gets deployed in a format that may be issue to consume by others?

Other projects in GSF use Docasaurus to build their documentation, an example such project is : https://github.com/Green-Software-Foundation/sci-guide , currently deployed to : https://sci-guide.greensoftware.foundation/

Best solution to this issue would involve - restructuring the current docs to be buildable and deployable as a Docasaurus project on github pages.

Code of Conduct

• I agree to follow this project's Code of Conduct

[Willmish]

We definitely want the latest docs to be reflected on the website. To be honest we should consider in general whether we should have a web deployed docs or keep it purely in GH.

I personally am for maintaining both, ideally keeping all documents in the docs folder so they are buildable with a tool like Sphinx https://www.sphinx-doc.org/en/master/ , we can then add a GH action that redeploys the docs on any changes to the docs/ folder

@vaughanknight @danuw what do you guys think?

FYI: Current docs deployed look like this: https://green-software-foundation.github.io/carbon-aware-sdk/

[Willmish]

Feedback from the Open Source WG: other GSF projects (SCI ) use docasaurus which use mdx files and would require some modification of existing documentation, but we would then stick with consistency

[Willmish]

Update during meeting #355 : no update on this yet, @danuw currently looking at other issues.

[Willmish]

Update #358 : no update, open for contributors to pick up - to bring up during OSS - where to add static content for the dcosaurs to build? Is it possible to do it dynamically from our docs folder as well?

[danuw]

Shouldn't we reopen this? Looks like it was closed by mistake @Willmish

(Started taking a look at docusaurus.

Looking at how it works for now and how to leverage the root docs folder ideally...)

[danuw]

@YaSuenag branch is on my fork at the mo.
To https://github.com/danuw/carbon-aware-sdk.git
ede7ab7..fbc602c docs/docusaurus-setup -> docs/docusaurus-setup

I have pushed everything - note I have not yet moved files from docs to casdk-docs/docs

Let me know if you need my help but I have a feeling what you are after is another folder (like blog and docs)

[Willmish]

form #384: @danuw to share screenshots from his local demo using the existing docs folder in the dev branch

@YaSuenag PR #359 has a ready generation of docs, but if we generate from a different branch the draft pr needs to be repointed to a different branch

This workflow also generates Javadoc (API document of Java library), so it should be published into doc-website branch.

[danuw]

Attaching some screenshots of what we currently have

Mobile and Desktop of the home page

Tutorial homepage and sidebar for now

[danuw]

done some clean up

which mostly expanded shows this...

[danuw]

Main challenge remaining is around sample docs... on how to integrate with it...

[danuw]

Hi @osamajandali, @jawache suggested to get in touch with you about this.

We are trying to revive the docusauraus/docs website for the repo. I currently have a branch that compiles to the above screenshots.

Considerations:

• using /casdk-docs folder for docusaurus
• copied /docs folder (into /casdk-docs) for the docs to show (I could not find a way to link to docs outside of the folder - having the docs under casdk has the expected benefit or UI updating and bad links being flagged as docs are updated

Latest hurdle to tackle is around docs available in the /samples. Ideal plan was to surface the .md files from the /samples folder (so have a top level section in the navigation for samples in above or below the architecture one). The issue is the same as with docs though it does make as sense in this case (vs moving the docs) to be in that sub folder. Samples should stay out of the folder. There is always the option to copy the files at compile time, but then would need to stop the process and relaunch for the file changes to be taken into account, so less than ideal.

Are you able to help? do you have any suggestions? Let me know
(Feel free to connect on slack too if easier so we can maybe talk about it.)

[osamajandali]

Hi @danuw,
I'd like to know which branch are you using, is it the dev branch or another?

[danuw]

Hi @osamajandali
thank you for getting in touch.
The information is in a comment above. This is on my repo and branch is docs/docusaurus-setup.

Can you access it?

[danuw]

Pending action here is that the deployment pipeline does not error but only works partially.

It deploys to https://green-software-foundation.github.io/carbon-aware-sdk/ but it is missing the layout (navigation and header bar).

This shows that changes get deployed - although I could test by adding a file in particular and removing it afterwards to make sure updates do occur (will test that now and report back)
https://green-software-foundation.github.io/carbon-aware-sdk/docs/overview

[danuw]

I think the deployment does not work actually ...

test file if visible in the locally run instance, but not in the github pages after the workflow successfully completed ...

@osamajandali any ideas please?

EDIT: additionally the file is in the gh-pages branch https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/gh-pages/docs/test.html

EDIT2: I am trying to go through the yarn deploy step to understand better what could fail (ref)

[danuw]

All sorted - basically I still needed the config to deploy from GitHub pages branch even though I have my own workflow to deploy.

So left to do:

• blogs pages for release notes and ensure link appears in the navigation
• logic to move the samples folder at build in the pipeline
• condition to make sure website only gets updates for main or dev updates - cc @vaughanknight we should confirm when we publish latest updates and if there are maybe options to have a dev instance and a main instance, but will assume we deploy the latest from dev for now
• apply the banner referenced in Add disclaimer banner to any public-facing documentation (docusaurus webpage) #416

[zanete]

thanks @danuw, would anything in that list you've added need input from @osamajandali or can I remove his name from the assignee list? 🙏

[danuw]

Hi @zanete you can remove. Thank you

[danuw]

(Fyi a copy paste of the themes from IF docs did not work out of the box, so something to come back to, after 1.3 release)

[danuw]

Workflow works

Remaining :

• rebase with dev
• sort out warning from samples folder (.md files broken links)
• cleanup docs folder

[danuw]

Order for reference

1. Project overview (ReadMe)
2. How to contribute (contributing.md )
3. End User Guide (enablement.md)
4. Test coverage
5. Fit within GSF Theory of Change
6. adopters.md
7. security.md

[Sophietn]

@danuw happy to close this issue off now?
(Docusaurus found at https://carbon-aware-sdk.greensoftware.foundation)

[danuw]

Sure that can probably be be closed but still waiting for PR to be approved by the team.

@zanete yes you can remove his name if you need. Thank you

[vaughanknight]

Carbon Aware SDK Tutorial?

[vaughanknight]

Tutorial link in the footer goes to 404