First experiment: stable-docs

[simonw]

I want to be able to publish updates to my /en/stable/ docs without needing to ship an entire release - for things like typo fixes and plugin directories.

My initial idea:

Have a stable-docs branch which is published by ReadTheDocs as the stable version.

Publish workflow force-updates that branch to be a copy of the tag that was just released

A file called _plugins.md lives in the repo and has the content for the plugins directory

Another workflow watches for changes to that file and automatically merges those changes into the stable-docs branch

So now… editing _plugins.md always goes live on stable-docs - and edits can be made on stable-docs to other stuff too, which will be over-written the next time a stable release is issued.

Would be good to have non-destructive merges into stable-docs when a release goes out just to avoid any chance of accidentally deleting edits made there that need to be preserved in history.

Also: any time you commit a change that modifies docs, tag it with !stable-docs and a workflow will automatically include that change in the current stable-docs branch.

[simonw]

Used GPT-4 to create an initial workflow for this: https://chat.openai.com/share/dbd19d7c-c022-4a11-9a52-7217316afd2a

[simonw]

The first run of that workflow created this branch: https://github.com/simonw/simonw-readthedocs-experiments/tree/stable-docs

[simonw]

https://readthedocs.org/dashboard/simonw-readthedocs-experiments/advanced/ has the default settings:

It's not giving me a "stable" option yet, maybe I need to ship a release?

[simonw]

Here's what that release did: https://github.com/simonw/simonw-readthedocs-experiments/actions/runs/5918859742/job/16048570940

No need for it to update the branch since there were no changes to it yet.

[simonw]

OK, ReadTheDocs noticed the release and created a stable version:

Now settings gives me the option to switch to that, which I'll do now: https://readthedocs.org/dashboard/simonw-readthedocs-experiments/advanced/

https://simonw-readthedocs-experiments.readthedocs.io/ now redirects to https://simonw-readthedocs-experiments.readthedocs.io/en/stable/

[simonw]

That commit triggered an error: https://github.com/simonw/simonw-readthedocs-experiments/actions/runs/5918907110/job/16048660640

simonw-readthedocs-experiments/.github/workflows/stable-docs.yml

Lines 25 to 30 in 03344fb

	- name: Check if stable-docs branch exists
	run: |
	if ! git rev-parse --verify stable-docs > /dev/null 2>&1; then
	git checkout -b stable-docs
	git push -u origin stable-docs
	fi

[simonw]

I think this test found that stable-docs did not exist even when it does:

if ! git rev-parse --verify stable-docs > /dev/null 2>&1; then

[simonw]

OK, that worked - the commit now skips the branch creation bit, but doesn't do anything else.

Next I'll test mentioning !stable-docs in a commit and see what happens.