Readthedocs.org: Define new spec for Sphinx template context data

[davidism]

RTD injects a bunch of template variables that are useful for theme designers. I only discovered this after talking with @ericholscher while working on porting the Flask theme for RTD. Especially useful to me is the versions list, because our theme wants to display version links in the sidebar. These should be documented (possibly here?).

[ericholscher]

I think this is actually about defining a proper "public template API" for projects. Currently most of the template data is mainly for internal use, and hasn't been thought of as a public API.

Define a new "public project Template API", that is namespaced

Currently we pollute the top-level html_context on the project build with a bunch of junk data. We should really namespace this. We should also document a standard JSON representation of the data, so that we can commit to maintaining this going forward. I think it's useful to think about this similarly to a Public REST API JSON response, in that we want to define a format that is abstracted from the underlying data model. We could even go as far as use the REST Framework Serializer for generating it.

I'm thinking it will be something like:

# In conf.py

html_context.update({
    'readthedocs': {
        'version': {
            'slug': 'foo',
            'latest': <Bool>,
            'stable': <Bool>,
        }
        'project': {
            'name': 'bar',
            'slug': 'foo',
            'rtd_language': u'{{ project.language }}', # Can be different than language in conf.py
            'canonical_url': '{{ project.get_canonical_url }}',
            'single_version': {{ project.single_version }},
            'versions': [
                <VERSION_JSON>,
                <VERSION_JSON>,
            ],
            'subprojects': [ 
                <PROJECT_JSON>,
                <PROJECT_JSON>,
            ]
        }
        'meta': {
            'READTHEDOCS': True,
            'html_theme': html_theme,
            'source_suffix': SUFFIX,
            'conf_py_path': '{{ conf_py_path }}',
            'api_host': '{{ api_host }}',
            'MEDIA_URL': "{{ settings.MEDIA_URL }}", 
            'PRODUCTION_DOMAIN': "{{ settings.PRODUCTION_DOMAIN }}",
            'user_analytics_code': '{{ project.analytics_code|default_if_none:'' }}',
            'global_analytics_code': '{{ settings.GLOBAL_ANALYTICS_CODE }}',
            'commit': '{{ commit }}',
        }
        'vcs': {
            'github_user': '{{ github_user }}',
            'github_repo': '{{ github_repo }}',
            'github_version': '{{ github_version }}',
            'display_github': {{ display_github }},
            'bitbucket_user': '{{ bitbucket_user }}',
            'bitbucket_repo': '{{ bitbucket_repo }}',
            'bitbucket_version': '{{ bitbucket_version }}',
            'display_bitbucket': {{ display_bitbucket }},
            'gitlab_user': '{{ gitlab_user }}',
            'gitlab_repo': '{{ gitlab_repo }}',
            'gitlab_version': '{{ gitlab_version }}',
            'display_gitlab': {{ display_gitlab }},
        }
    }
})

I haven't fully "scrubbed this", but you get the idea.