singularity-energy / open-grid-emissions

Tools for producing high-quality hourly generation and emissions data for U.S. electric grids
MIT License
67 stars 4 forks source link

Adds the documentation to the repository with the code #303

Closed Rdbaker closed 10 months ago

Rdbaker commented 11 months ago

This PR:

Moves the documentation from the (private) docs repo to the public repository.

Since the docs live at https://docs.singularity.energy/docs/open-grid-emissions-docs in public, it's fine to have the .md and static files powering them be public as well

What isn't included here (but should be) is the steps to deploy these markdown files. Unfortunately, I also didn't see that in the other repository.

Rdbaker commented 11 months ago

I was looking into Stoplight a bit more and it turns out that we can't change the GitHub repo that Stoplight is looking at. Unfortunately, this means that, in order to have the docs and code in the same place, we'll have to change the URL of the docs. (from https://docs.singularity.energy/docs/open-grid-emissions-docs to https://docs.singularity.energy/docs/open-grid-emissions)

This is probably worth it, but I just wanted to call it out before we made any changes.

Thoughts @gailin-p @grgmiller ?

gailin-p commented 11 months ago

I think it's fine to change the .url as long as we change the link on the OGE webpage (https://singularity.energy/open-grid-emissions) but will defer to Greg

grgmiller commented 11 months ago

Fixes https://github.com/singularity-energy/open-grid-emissions/issues/250

grgmiller commented 11 months ago

Ok it sounds like to move this forward, here's next steps: Problem: Previously, we had been maintaining previous versions of the documentation in stoplight by taking advantage of the feature that you can use repo branches as previous versions. However, we do not want to maintain historical versions of the entire OGE repo on branches because 1) it will clutter up our branches and 2) we already archive previous versions as releases. Solution Option A: Instead of archiving previous versions of the documentation in stoplight, we could export the entire stoplight documentation for previous versions as a PDF document and then create a page in the stoplight documentation where these archived versions can be uploaded and linked to so they are still accessible. However, I'm not sure if there's an easy way to print/export the documentation. See: https://meta.stoplight.io/docs/platform/37d160068e33c-export-files and https://blog.stoplight.io/pdf-api-documentation Solution Option B: Instead of maintaining a branch for every single previous version of OGE, we could maintain a single "previous-version" branch that we update each time we release a new version. This way the most recent previous version documentation (which most people would likely need) is easily accessible, and documentation beyond that is still archived in the release zipfile.

Maybe we want a hybrid of these approaches, especially since all releases to date will not have included the documentation in the version release. i.e. we should create PDF versions of the previous documentation that we can host, but also make the most recent previous documentation easily accessible in stoplight format as well.

@Rdbaker @gailin-p thoughts?