microbiomedata / NMDC_documentation

Document workflows, schemas, and portal
https://nmdc-documentation.readthedocs.io
2 stars 3 forks source link

Document process of deploying documentation updates #58

Open eecavanna opened 4 months ago

eecavanna commented 4 months ago

This PR is about how we get from "we've made changes within the repo" to "our documentation website (currently Read The Docs) reflects those changes."

For reference, this other PR is about editing the content of the repo: https://github.com/microbiomedata/NMDC_documentation/issues/8

eecavanna commented 1 month ago

Also, document the process of deploying from non-main branches to the dev-nmdc-documentation website.

I think there are specific branches that the readthedocs.org website is aware of (one of which branches is named dev) that, if we merge code into those, we can use the readthedocs.org dashboard to make a build from that branch. I didn't find a way to get the readthedocs.org dashboard to see newly-created branches; so, I assume the current list of branches was defined at the time when the readthedocs.org project was first created (maybe readthedocs.org did a big pull of branch names at that time).

So, one workflow for deploying from a non-main branch to the dev-nmdc-documentation website could be:

  1. Merge the changes into the dev branch (or another one of the branches that readthedocs.org already "sees")
  2. Use the readthedocs.org dashboard to activate that branch as a source (if not already active)
  3. Use the readthedocs.org dashboard to create a build from that source

    image

  4. Visit the resulting website; for example (note the final path segment in the URL):