A short hack to deploy reveal.js presentation on Read the Docs

This is an introduction to serve reveal.js slide to Read the docs.

Abstract

Edit your conf.py to override target builder.

<span>def</span> <span>override_builder</span><span>(</span><span>app</span><span>,</span> <span>config</span><span>):</span>
    <span># Change for your RTD settings. Please set it in your RTD prject </span>    <span>app</span><span>.</span><span>registry</span><span>.</span><span>builders</span><span>[</span><span>"singlehtml"</span><span>]</span> <span>=</span> <span>app</span><span>.</span><span>registry</span><span>.</span><span>builders</span><span>[</span><span>"revealjs"</span><span>]</span>
<span>def</span> <span>setup</span><span>(</span><span>app</span><span>):</span>
    <span>app</span><span>.</span><span>connect</span><span>(</span><span>"config-inited"</span><span>,</span> <span>override_builder</span><span>)</span>
<span>def</span> <span>override_builder</span><span>(</span><span>app</span><span>,</span> <span>config</span><span>):</span>
    <span># Change for your RTD settings. Please set it in your RTD prject </span>    <span>app</span><span>.</span><span>registry</span><span>.</span><span>builders</span><span>[</span><span>"singlehtml"</span><span>]</span> <span>=</span> <span>app</span><span>.</span><span>registry</span><span>.</span><span>builders</span><span>[</span><span>"revealjs"</span><span>]</span>

<span>def</span> <span>setup</span><span>(</span><span>app</span><span>):</span>
    <span>app</span><span>.</span><span>connect</span><span>(</span><span>"config-inited"</span><span>,</span> <span>override_builder</span><span>)</span>
def override_builder(app, config):
    # Change for your RTD settings. Please set it in your RTD prject     app.registry.builders["singlehtml"] = app.registry.builders["revealjs"]

def setup(app):
    app.connect("config-inited", override_builder)

Enter fullscreen mode Exit fullscreen mode

You can see contents and sources.

• https://github.com/attakei-sandbox/sphinx-rtd-revealjs
• https://sphinx-rtd-revealjs.readthedocs.io/en/latest/

Approaching

Problems for regular usage to server sphinx-revealjs

Read the docs are documentation platform supporting Sphinx.
You can serve HTML files from Sphinx documentation as same as run make html on local.

sphinx-revealjs is Sphinx extension to provide builder that generate Reveal.js style HTML. (ex: call make revealjs)

RTD supports only html, dirhtml and singlehtml for HTML buildings.
So, it is difficult to server reveal.js presentation of sphinx-revealjs.

Sphinx can override builder object

Sphinx provides Application API to inject procedures on some events.
config-inited event is called on after loading all configuration before creating target-builder object.

We can modify builder-class in the handler for this event, and can use any builder in RTD.
(please see abstract for example)

Caution

Cannot serve regular name builds

This hack switches the builder, and you cannot use regular builder.
You should be careful what builder you want to call.

RTD widget is not working

RTD provides widget for versioning and i18n.
But reveal.js content does not render wighet.
You can serve single version presentation only!

This hack is NOT clean

This is dirty hack.
RTD may not accept this hack in backend.

原文链接：A short hack to deploy reveal.js presentation on Read the Docs