readthedocs.org: How does read the docs detect tags and build /stable/ when triggering via the api?

Details

so, looks like the default behavior is this: read the docs wants a /latest/ and /stable/

Stable follows /branch/ unless it sees a tag then it follows the tag.

I don’t really understand how the tag detection works if you are not using a webhook When using the api is readthedocs going to see all the new tags? and automatically build /stable/ and if so how does it do this?

User created a branch. (amber) User tagged this branch at the same location it was created (1.3.0) (So the tag and the head of the branch are the same ref)

no builds are triggered by our CI when a branch is created, this is fine. the next time a user updates that branches docs/ directory the branch will be created in read the docs as expected.

lftools rtd project-build-trigger o-ran-sc-portal-ric-dashboard amber

however, in testing I triggered on that branch manually

lftools rtd project-build-trigger o-ran-sc-portal-ric-dashboard amber

This casued read the docs to trigger a build for /amber/ and /stable/

The build shows that It did a: git checkout --force origin/amber

Which pulled down this commit. commit cec131cf4b0279bd6a6d4dd31642270cebe38711 (HEAD, tag: 1.3.0, origin/amber)

The head of my branch of “amber” happens to have a tag on it. My guess read the docs saw the tag and decided to trigger a build /stable/ after it was done with /amber/

/stable/ is following type “tag” and not the branch “amber”

lftools rtd project-version-details o-ran-sc-portal-ric-dashboard stable
<snip> 
'ref': '1.3.0',
'slug': 'stable',
'type': 'tag',

I did not expect this behavior. Does read the docs have a way to detect tags if the build I trigger has a new tag somewhere in the history? Or it it only detecting the tag because it exists at the head of the “amber” branch?

Thanks for your time.

About this issue

Original URL
State: open
Created 5 years ago
Comments: 15 (6 by maintainers)

Commits related to this issue

RTD Allow projects to change their default-version Allow docs release via jjb config Changes the default landing page from /latest/ to /stable/ by default we se to /latest/ (a no-op) And on release ... — committed to lfit/releng-global-jjb by Aricg 5 years ago

Most upvoted comments

So I re-read the docs, and /stable/ is only created (and enabled automatically for that matter) if a tag is pushed, so I think the docs needs some clarification.

https://docs.readthedocs.io/en/stable/versions.html#tags-and-branches “Read the Docs supports two workflows for versioning: based on tags or branches. If you have at least one tag, tags will take preference over branches when selecting the stable version.”

But /stable/ will never get created unless you do push a tag. so “take preference” doesn’t make sense in this case afaict, I can’t see how stable will ever point to the head of a branch, or how to make /stable/ exist without having pushed a tag.

Aricg on Jan 21, 2020