manual-integrations

Initial PoC to manually integrate all the Read the Docs features. Context:

Read the Docs configuration file used to build this docs:

 1version: 2
 2
 3build:
 4  os: ubuntu-22.04
 5  tools:
 6    python: "3"
 7  commands:
 8    # Run all the commands manually to avoid installing pre-defined packages
 9    # Make explicit what are the dependencies we are installing
10    - pip install sphinx sphinx-autorun
11
12    # Install latest release candidate of "sphinx-rtd-theme".
13    # This version injects ``data-content_root`` on the HTML tag required for search
14    - pip install "sphinx-rtd-theme>=2.0.0rc4"
15
16    - sphinx-build -b html docs/ _readthedocs/html
17
18    # Copy data from the builder
19    # This will exposed via `/_/readthedocs-config/` API endpoint
20    - cp docs/readthedocs-build.yaml _readthedocs/html/

Sphinx configuration file used to build this docs (see full file),

 1import os
 2
 3# Default settings
 4project = 'Test Builds'
 5extensions = [
 6    'sphinx_autorun',
 7]
 8
 9# Include all your settings here
10html_theme = 'sphinx_rtd_theme'
11
12html_theme_options = {
13    'enable_search_shortcuts': False,
14}
15
16template_path = [
17    "templates",
18]
19
20# We need to tell to our builder that we are building on Read the Docs
21# Ideally, the theme should get this automatically from the environment
22# instead of forcing us to define it on its context
23#
24# Note that Read the Docs is passing a lot of context here:
25# https://github.com/readthedocs/readthedocs.org/blob/e18b40f6fe7c2c058bbf681063c1c577b5e8e9d3/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl#L99-L149
26# We would need to audit all of it, remove the ones that are not required,
27# and adapt our Sphinx theme to use environment variables --which will be the
28# official way to communicate with all the builders
29#
30# For now, I'm only defining the variables I need to build the `versions.html` from the theme
31# https://github.com/readthedocs/sphinx_rtd_theme/blob/9d88b9e4e1e17896c6231358a89da4612ff7bc90/sphinx_rtd_theme/versions.html#L1
32# Note that everything from inside "rst-other-versions" is gonna be replaced by the `/footer_html/` response,
33# so they are not needed to be defined.
34# if "READTHEDOCS" in os.environ:
35#     html_context = {
36#         "READTHEDOCS": True,
37#         "current_version": os.environ.get('READTHEDOCS_VERSION'),
38#     }

>>> # Build at
>>> import datetime
>>> datetime.datetime.utcnow()  # UTC
datetime.datetime(2024, 2, 1, 18, 13, 11, 175736)