Document theme developer development/mocking patterns

[ericholscher]

Theme developers need:

• Versions, Translations, Search, etc.
• Edge case test data

rtd_project = 'theme-test'
html_js_files = ['media.readthedocs.org/client/v1.js']

[humitos]

We talked about documenting:

• how to include the .js client in an agnostic way (and in particular in Sphinx)
• expose a hardcoded API response so developers can get the .js working properly (see what we are doing at public/_/readthedocs-config.json)

[agjohnson]

The context of this issue isn't clear, but probably some overlap with discussion at #51

[humitos]

@agjohnson the description is not clear, yeah. We wrote it quickly while talking at PyCon to not forget about it.

The main idea here is to allow theme authors to include our client in a simple way and return/mock/hardcode some dummy data to be received when readthedocsdataready is triggered (see #64) so they can work on developing the integration with Read the Docs without having to connect to the real API and setup multiple things.

We talked about this when we saw what @pradyunsg was doing on furo to be able to test the current integration with Read the Docs. The idea is to simplify this chunk of code https://github.com/pradyunsg/furo/blob/main/docs/conf.py#L114-L132

Does this clarify a little what is required on this issue?

[agjohnson]

Yeah I figured this was a note, thanks for clarifying.

Having a mocking pattern documented, or even available in our API, would be a great addition.

[humitos]

I wrote some steps in the PR description of readthedocs/sphinx_rtd_theme#1526 that will be useful to document this issue. It requires the Read the Docs development instance up, which is not good, but I think we can slightly modify the code to don't require that.