Closed Rdbaker closed 10 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 ?
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
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?
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.