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

[Aricg]

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?

• https://docs.o-ran-sc.org/projects/o-ran-sc-portal-ric-dashboard/en/stable/
• https://readthedocs.org/projects/o-ran-sc-portal-ric-dashboard/builds/10031106/
• lf-oran

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.

[humitos]

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/

I don't know what this commands does behind the scenes. Although, if it's using APIv3 endpoint (https://docs.readthedocs.io/en/latest/api/v3.html#build-triggering), it should not trigger a build for stable version, only for amber

[Aricg]

I think that the first time you build a branch it automatically builds stable, no?

[stsewd]

So, when we detect at least a tag, we give more priority to tags. When you trigger a build to any version, rtd clones the repo and gets the branches and tags from there. Then it updates the versions, when updating the versions, it checks if the stable version has changed (new tag or new branch with a version greater than the current stable), it also triggers a build to latest if master has changed. Hope that answer your question.

[Aricg]

@stsewd Can you be more specific?

If I trigger a build, say "latest" or "master" and there is a new ref tagged somewhere, read the docs lists all tags and branches internally and keeps track of that? so I could say only trigger only /latest/ (which maps to master) in my CI and new tags detected would automatically trigger /stable/ for me?

[Aricg]

"it also triggers a build to latest if master has changed. Hope that answer your question."

This statement adds to my confusion, my experience is that this does not hold true.
When a build was triggered via curl, using a the old method:
"generic api integration"

curl -X POST -d "branches=${GERRIT_BRANCH}" -d "token=$RTD_TOKEN" "$RTD_BUILD_URL

this returned for example:

{"build_triggered":true,"project":"o-ran-sc-doc","versions":
["latest","master"]}

So the previous behavior was to build latest and master from a call with
branches=master

when we post via the v3 api.
lftools rtd project-build-trigger "$rtdproject" "$STREAM"

It actually respects the $STREAM variable and only builds "master"

Here is my patch that keeps /latest/ /master/ in sync:
https://gerrit.linuxfoundation.org/infra/c/releng/global-jjb/+/62314

I am trying to understand what I need to do to keep /stable/ in sync,

This is what I have so far
the api implementation does as you mentioned
POST /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/builds/

STREAM is one of 'master' or 'branch'

  lftools rtd project-build-trigger "$rtdproject" "$STREAM"
  if [[ $STREAM == "master" ]]; then
    lftools rtd project-build-trigger "$rtdproject" latest
  else
    lftools rtd project-build-trigger "$rtdproject" stable
  fi

[stsewd]

If I trigger a build, say "latest" or "master" and there is a new ref tagged somewhere, read the docs lists all tags and branches internally and keeps track of that? so I could say only trigger only /latest/ (which maps to master) in my CI and new tags detected would automatically trigger /stable/ for me?

When you trigger any build, before building the docs, we collect information about the repo, like branches and tags. If we detect a new tag or branch (and it's greater than the current stable, a build is triggered for the new stable). Or if the latest branch (master) changes, we trigger a new build to latest too.

Also, if you have set up the webhook to send the events when a tag or branch is pushed/created/deteled, rtd can update/build automatically stable and latest https://docs.readthedocs.io/en/stable/webhooks.html#github.

[stsewd]

Ok, I think I understand better what you mean and what we are doing :D.

You were using the generic integration bc you are not using github, but a self hosted git server.
All the integrations receive the name of the branches/tags to build.

RTD can have more than one version linked to one name of a branch/tag. This is the case of LATEST and STABLE. The branch name master is linked to the version master and latest. The branch name 2.0 (for example) will be linked to the version stable and 2.0.

API v3 search for slug only (not for the name of the branch/tag), that's why it only triggers one build.

Both methods will still sync the versions when a build is triggered. And update stable. Looks like master/latest isn't updated when using apiv3.

I think we should update latest/master in the same place we do it for stable, and not update it only when it's received from a webhook.

[chrisinmtown]

Trying to follow @stsewd explanations. I guess that all changes on git branch "master" are exposed in RTD under the name "latest". Many teams use "master" branch as the development branch, so I think I follow. But what is "stable"? Naively I read that word as implying a version has passed some kind of validation. But I don't see how RTD can possibly know about any such thing.

[stsewd]

@chrisinmtown you can read more about stable here https://docs.readthedocs.io/en/stable/versions.html

And yes, latest is an alias for master (but users can change that)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Aricg]

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.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ssbarnea]

I think that I found a big flaw in the current logic and I have no idea how to address it. We created a latest tag which is a mobile tag used in parallel with normal versioned tags.

The side effect of this is that now the documentation no longer builds on main branch.

The only version enabled in RTD is named 'latest' and there are no options to configure it. Because it happens to be a tag with same name, we no longer build main.

Is there something we can do to keep building documentation from main branch while not removing the latest tag?

[stsewd]

Is there something we can do to keep building documentation from main branch while not removing the latest tag?

You can activate the "main" version on RTD, or deactivate the latest tag.
If you deactivate the tag, you won't be able to build docs from that tag.

If you can link me to your RTD project, I can look into what exactly the solutions can be for your case.