Hosting presentation on Read the Docs

This is updates of previous post.

About Read the Docs

Read the Docs(RTD) is "documentation platform" to host website about document of software.
RTD can integrate with GitHub. If integrated repository has .readthedocs.yaml, build sources and deploy contents when it is pushed.

Example of .readthedocs.yaml for standard Sphinx:

version: 2

build:
  os: 'ubuntu-22.04'
  tools:
    python: '3.11'

sphinx:
  configuration: docs/conf.py
  builder: dirhtml

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

On push event, RTD runner works these:

1. Set up Python 3.11 (ref: build.tools)
2. Install dependencies by docs/requirements.txt (ref: python.install)
3. Build document by dirhtml builder using docs/conf.py (ref: sphinx)

Custom build supportings

There is build.commands property in .readthedocs.yaml that define procedures to build contents from source.
as far as it outputs contents into specified path, RTD deploy it as published site.

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  commands:
    - pip install pelican
    - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

This is example on reference about build.commands.
It runs pelican (other website build of Python) and output $READTHEDOCS_OUTPUT/html.

Anything is ok that programs generate html files.
Even if it generate presentation.

Deploy presentation on Read the Docs

version: 2

build:
  os: 'ubuntu-22.04'
  tools:
    python: '3.11'
  commands:
    - pip install -r requirements.txt
    - sphinx-build -b revealjs source $READTHEDOCS_OUTPUT/html

This is .readthedocs.yaml of example for deploy Reveal.js presentation by sphinx-revealjs.

There is generated presentation.

Pros and Cons

Pros

• Keep older presentation for users (e.g. seeing archive movie of YouTube).
  • Presentation should be fixed for typo and more.
  • If author update with bigger changes, user can see old version.
• It can toggle version by bundle widget of RTD.
• It can be visible or hidden manually.

Cons

• RTD adds AD on presentation.
• Presentation does not root of FQDN.