Build the docs using Docker

[bertiewooster]

FWIW, if building just the HTML docs is enough, then the following Dockerfile seems to work:

FROM python:3.8.12-slim-buster

RUN apt-get update
RUN apt-get install -y make librsvg2-bin imagemagick graphviz git

COPY requirements.txt /tmp
RUN egrep "phinx|mpmath|matplotlib" /tmp/requirements.txt > /tmp/req_min.txt
RUN pip install --upgrade pip
RUN pip install -r /tmp/req_min.txt

CMD cd /sympy/doc; make html

If you saved this as release/Dockerfile.htmldoc, then you could build the image with

$ cd release
$ docker build -f Dockerfile.htmldoc -t sympy_htmldoc .

and once you had the image you could build the docs at any time with

$ docker run --rm -v /path/to/the/sympy/repo:/sympy sympy_htmldoc

The image weighs in at 679MB. If you wanted to also build LaTeX docs I think the image might be 5 to 10 times as large. But I find HTML docs are enough, if I just want to check that things are looking about right.

Originally posted by @skieffer in #22629 (comment)

I think it would make more sense to put the Docker file in the doc directory. The instructions for building the docs could be updated to suggest using it as an option.

Originally posted by @oscarbenjamin in #22629 (comment)

[bertiewooster]

@skieffer So that folks can build the documentation easily, does it make sense to:

• Have the Dockerfile clone the sympy-live repo into folks' sympy site-packages folder (sympy-live was required to build the documentation, at least using the non-Docker method)?
  • Note: the Dockerfile would have to rename the site package from sympy-live to sympylive (removing the hyphen), unless we change doc/src/conf.py extensions command from sympylive to sympy-live)
• Include pip install commands for all the required Sphinx extensions in the Dockerfile, that is
  • pip install numpydoc
  • pip install sphinx_math_dollar
  • pip install matplotlib.sphinxext.plot_directive?
• Allow folks to use conda (instead of "straight" python) by creating another version of the Dockerfile with conda install instead of pip install commands?

[skieffer]

Well, I could be misunderstanding the setup/goals you have in mind, but off the top of my head I would think that none of these steps should be necessary. The Dockerfile builds an image that is self-sufficient and operates independently of your local dev environment. In other words, you never needed to install any Sphinx packages etc. on your own computer in order for this to work (and building the image doesn't install anything on your computer either). The volume mount

-v /path/to/the/sympy/repo:/sympy

in the docker run command lets the container read the code from your sympy/sympy directory, and write the docs into your sympy/doc/_build/, but apart from that everything happens inside the container.

[skieffer]

That being said, if the file is going to live under the doc directory (which I think does make sense), then the build instructions change a little bit. These should probably be commented into the Dockerfile itself, in addition to being described in the docs page you're planning to write.

So, maybe the full file should live at doc/Dockerfile.htmldoc and look like this:

###############################################################################
# This Dockerfile can be used to build an image where the HTML docs for SymPy
# can be built.
#
# If SYMPY_ROOT is the directory where the sympy repository lives, then you can
# build the image with
#
#   $ cd SYMPY_ROOT
#   $ docker build -f doc/Dockerfile.htmldoc -t sympy_htmldoc ./release
#
# Once the image is built, you can build the docs at any time (and from any
# directory) using
#
#   $ docker run --rm -v /absolute/path/to/SYMPY_ROOT:/sympy sympy_htmldoc
#
# (substitute the actual absolute filesystem path to SYMPY_ROOT).
#
###############################################################################

FROM python:3.8.12-slim-buster

RUN apt-get update
RUN apt-get install -y make librsvg2-bin imagemagick graphviz git

COPY requirements.txt /tmp
RUN egrep "phinx|mpmath|matplotlib" /tmp/requirements.txt > /tmp/req_min.txt
RUN pip install --upgrade pip
RUN pip install -r /tmp/req_min.txt

CMD cd /sympy/doc; make html

[bertiewooster]

@skieffer ah, forgive my ignorance, I've never used Docker before. Great! I'd just suggest adding (to the doc/Dockerfile.htmldoc comments) where the documentation will be built:

###############################################################################
# This Dockerfile can be used to build an image where the HTML docs for SymPy
# can be built.
#
# If SYMPY_ROOT is the directory where the sympy repository lives, then you can
# build the image with
#
#   $ cd SYMPY_ROOT
#   $ docker build -f doc/Dockerfile.htmldoc -t sympy_htmldoc ./release
#
# Once the image is built, you can build the docs at any time (and from any
# directory) using
#
#   $ docker run --rm -v /absolute/path/to/SYMPY_ROOT:/sympy sympy_htmldoc
#
# (substitute the actual absolute filesystem path to SYMPY_ROOT).
#
# The documentation will be built in SYMPY_ROOT's doc/_build/html directory
#
###############################################################################

FROM python:3.8.12-slim-buster

RUN apt-get update
RUN apt-get install -y make librsvg2-bin imagemagick graphviz git

COPY requirements.txt /tmp
RUN egrep "phinx|mpmath|matplotlib" /tmp/requirements.txt > /tmp/req_min.txt
RUN pip install --upgrade pip
RUN pip install -r /tmp/req_min.txt

CMD cd /sympy/doc; make html

Would you, as the Dockerfile author, like to create the pull request? I'm also happy to, or someone else could.

[skieffer]

Yes, definitely agree the last sentence should be added!

Could maybe even offer a helpful tip about $ python -m http.server to start up a quick web server.

Okay, I'll open a PR.

[bertiewooster]

@skieffer the Dockerfile now gives an error after merge of #22472:

(venv) sympy % docker run --rm -v /Users/jemonat/Projects/sympy:/sympy sympy_htmldoc
mkdir -p src/.static
mkdir -p _build/html
mkdir -p _build/doctrees
mkdir -p src/modules
sphinx-build -b html -d _build/doctrees -W --keep-going src _build/html
Running Sphinx v4.1.2

Extension error:
Could not import extension myst_parser (exception: No module named 'myst_parser')
make: *** [Makefile:60: html] Error 2

FYI, myst_parser is in requirements.txt.

[skieffer]

Thanks for the heads-up! I've pushed an updated version.

If you rerun the docker build command with the new Dockerfile, it should once again be usable.

[asmeurer]

Maybe we should just create a separate docs/requirements.txt. That would be more generally useful.

[skieffer]

Sounds good.

Also updated commented instructions in Dockerfile accordingly.

[bertiewooster]

@skieffer Thanks! It worked when I used your new doc/Dockerfile.htmldoc and reran the docker build command.

It will definitely make building the documentation easier when your code changes are merged into the master branch!

[skieffer]

Okay, sounds like we're in agreement, so I'm setting it to merge after tests pass.

[asmeurer]

By the way, make livehtml will also open a live server, and in addition, it live rebuilds the docs whenever an update is made.