How to build with the ReadTheDocs Docker container

[westurner]

The RTD containers have multiple versions of Python and e.g. all of LaTeX installed:
https://hub.docker.com/r/readthedocs/build/

• https://github.com/readthedocs/readthedocs-docker-images/
• https://github.com/readthedocs/readthedocs-docker-images/blob/master/Dockerfile
• https://docs.readthedocs.io/en/stable/development/buildenvironments.html
• https://docs.readthedocs.io/en/stable/builds.html

An excerpted Dockerfile and Makefile for building docs with the ReadTheDocs container:
https://gist.github.com/westurner/9827e4d2665d08832ad37343085721d3

[ammaraskar]

Hey @westurner, sorry for the late reply. Could you give me a quick explanation of what the use case here is? Do you have an example of a full repo where someone utilizes the RTD containers for their documentation builds?

From my other project: https://pycraft.readthedocs.io/en/latest/, most of the setup is done so that it just looks like a plain-old sphinx project https://github.com/ammaraskar/pyCraft/tree/master/docs and then RTD handles the building portion.

Is this so you can build the documentation with different versions of Python or automatically handle installing LaTeX etc?

[westurner]

Use Case: Building docs with a maintained container with any recent version of Python and all of LaTeX preinstalled (which is necessary for building PDFs with Sphinx). Just like RTD but locally or with any CI that builds with containers. Thought I'd link these here. Have you seen anything for hosting multiple versions of docs with just GitHub Pages?

…

On Sat, Feb 15, 2020, 8:03 PM Ammar Askar ***@***.***> wrote: Hey @westurner <https://github.com/westurner>, sorry for the late reply. Could you give me a quick explanation of what the use case here is? Do you have an example of a full repo where someone utilizes the RTD containers for their documentation builds? From my other project: https://pycraft.readthedocs.io/en/latest/, most of the setup is done so that it just looks like a plain-old sphinx project https://github.com/ammaraskar/pyCraft/tree/master/docs and then RTD handles the building portion. Is this so you can build the documentation with different versions of Python or automatically handle installing LaTeX etc? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9?email_source=notifications&email_token=AAAMNSZ5W57B2OIMHRQVUTTRDCGGRA5CNFSM4KR6IHDKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEL3223I#issuecomment-586657133>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMNS5EMTKI33YSBJCCL5LRDCGGRANCNFSM4KR6IHDA> .

[duhd1993]

Sphinx team also provides a docker image with latex. It’s smaller than the RTD one, but just enough for most use cases. I’d like to see the action allowing customization of Image used. Not sure if it’s doable. Might be easier to just fork and change the image name.

[westurner]

To build MyST Markdown (with docutils and Sphinx roles and directives), jupyter-book has these
https://github.com/executablebooks/jupyter-book/blob/947b30f077dae7e39e34861360850dde3db67745/setup.py#L65 install_requires edit: and also docs/requirements.txt ::

install_requires=[
        "pyyaml",
        "docutils>=0.15",
        "sphinx>=2,<4",
        "linkify-it-py~=1.0.1",
        "myst-nb~=0.11.1",
        "jupytext~=1.8.0",
        "click",
        "setuptools",
        "nbformat",
        "nbconvert<6",
        "jsonschema",
        "sphinx_togglebutton",
        "sphinx-copybutton",
        "sphinx-comments",
        "sphinxcontrib-bibtex~=2.1.0",
        "sphinx_book_theme>=0.0.39",
        "sphinx-thebe>=0.0.6",
        "sphinx-panels~=0.5.2",
        "nested-lookup~=0.2.21",
    ],

• https://github.com/docker-library/python/blob/master/Dockerfile-slim.template (debian)
  • https://github.com/sphinx-doc/docker/blob/master/base/Dockerfile
    • https://github.com/sphinx-doc/docker/blob/master/latexpdf/Dockerfile
      • RUN python3 -m pip install jupyter-book gh-pages

[westurner]

Have you seen anything for hosting multiple versions of docs with just GitHub Pages?

Could set the BUILDDIR to /docs/_build/html/./en/{revtag}/ and then add the /index.html and /en/latest/index.html pages with a templated HTML meta and/or JS redirect to the configured latest revtag URL: /en/v1.0.5/