Somehow, tagging a release is creating "main" docs

[mattip]

📚 The doc issue

In #4687 I needed to change all the page's title and version. It seems tagging the version builds and uploads the docs to the gh-pages branch properly, but somehow the tag is not propagated into the doc build.

Also the last tag pushed generated docs/0.11. (with a '.' at the end) due to #4693. So that "proves" that the CIRCLECI_TAG is properly read in the CI, but something else is a bit off. So right now there are 0.11 docs and 0.11. docs, where the correct ones are 0.11.

I will try to figure out what is going on, and in any case immediately submit a PR to

• move the 0.11. docs on top of the 0.11 ones
• replace all the version/title info with 0.11.0

@brianjo

Suggest a potential alternative/fix

No response

[mattip]

Here is what is going on:

pytorch

1. circleci uses a script python_doc_push_script.sh with two arguments. The second is either main or a tag like v1.11.0.
2. Inside the script that value becomes version, that is used to determine is_master, which in turn is used to either call make html or make html-stable.
3. Inside the Makefile,html-stable sets the RELEASE environment variable
4. Inside the sphinx conf.py, the presence of RELEASE changes the version string from master (1.11.0a0+gitc0f53f1 ) to v1.11.0 and the html_title from "Pytorch documentation - master documentation` to Pytorch documentation - v1.110 documentation

audio

The tagged commit manually changes the version and release' instead of using any automation

text

They always use version = torchtext.__version__. Their unstable documents have a version like 0.12.0.dev20211026 without the master prefix. When tagging, the torchtext.__version__ becomes the cleaner 0.12.0.

vision (this repo)

No adaptations are done for a tagged release. Thus we need to manually replace the main 0.12.0.dev20211026 with the 0.12.0 text in the html documentation.

Conclusion

The maintainers should choose one of the three solutions above

• a complicated CI script with automation to get exactly the desired texts
• manually maintaining the release tag in the release branch to get exactly the desired texts
• use __version__ which is simpler all around.

@brianjo -FYI

[mattip]

@malfet, @NicolasHug any thoughts which option you prefer?

[brianjo]

Looks like the text model is the best option. @malfet Nikita, what do you think?