Docs: explain how to enable Read the Docs integrations when using build.commands

[humitos]

When using build.commands none of the Read the Docs extensions are installed. However, there are use cases where people want to fully overwrite the build process but still keep some of the integrations they like: "Version warning" and "External version note".

These can be configured manually by:

1. Install the dependencies: pip install readthedocs-sphinx-ext
2. Configure the extension in your docs/conf.py

extensions = [
  "readthedocs_ext.readthedocs",
  # ... other extensions ...
]

if os.environ.get("READTHEDOCS_VERSION_TYPE", None) == "external":
  extensions.insert(1, "readthedocs_ext.external_version_warning")

  # FIXME: these two URL are not passed as environment variables
  readthedocs_vcs_url = ""
  readthedocs_build_url = ""

With these changes, people should be able to have these integrations when using build.commands. I'm currently marking it as blocked because there are some data missing that should be passed via environment variables.

Reference: #8208 (comment)
Related: #9088

[buhtz]

If someone is interested. Here you find a configuration where I use build.commands to run pydoctor instead of sphinx.

https://codeberg.org/buhtz/buhtzology/src/commit/9c83f155c2de9c4656ced8a0451eaa35bf268036/.readthedocs.yaml

[humitos]

We won't be documenting this. We switched direction here and we are implementing all these features in Javascript via our Read the Docs client (https://github.com/readthedocs/readthedocs-client). We are calling these set of features "addons".

Some of them are currently enabled by default on projects using build.commands. These features are: analytics and PR version notification. I just confirmed that the new JS client is being loaded on https://buhtzology.readthedocs.io/en/develop/ and is working fine 👍🏼

I'm going to close this issue because the original work is not happening.