[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?