Document theme developer development/mocking patterns

readthedocs / addons

JavaScript client to integrate with Read the Docs nicely

https://readthedocs-addons.readthedocs.io/

MIT License

15 stars 3 forks source link

Document theme developer development/mocking patterns #59

Open ericholscher opened 1 year ago

ericholscher commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

humitos commented 1 year ago

@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 commented 1 year ago

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 commented 11 months ago

I wrote some steps in the PR description of https://github.com/readthedocs/sphinx_rtd_theme/pull/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.