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:
- Set up Python 3.11 (ref:
build.tools
) - Install dependencies by docs/requirements.txt (ref:
python.install
) - 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.
Top comments (0)