search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.59k stars 2.12k forks source link

Providing official docker image #3566

Closed tk0miya closed 4 years ago

tk0miya commented 7 years ago

To use Sphinx simply, it would be nice if we provides official docker image. Does anyone have example or idea?

tk0miya commented 7 years ago

https://github.com/tk0miya/sphinx-docker is my playground :-)

which base image?

I used Ubuntu 16.04 LTS.

what package should we install?

Please refer my Dockerfile.

how to test it?

Not tested yet.

Is it contains TeXLive? it is very large...

I separated containers for each builders. Only pdf image contains TeXLive.

boy-vd commented 5 years ago

I'm very new to commenting in GitHub so I'm not sure if this is the proper way of giving feedback, but I would like to propose to use a smaller base image for the official Sphinx Dockerfile. I just built the base-html variety and it seems to be 635MB.

For example, with the very simple Dockerfile below, which uses the official Python Docker image for Alpine Linux, I can build a Sphinx Docker image that is about 166MB, including the sphinx_rtd_theme that I use to build documentation with:

FROM python:3.5.6-alpine3.9

RUN apk --update add make \
 && rm -f /var/cache/apk/*

RUN pip install 'Sphinx                        == 1.8.5' \
                'sphinx_rtd_theme              == 0.4.3'

CMD ["make", "clean", "html"]

Potentially, the image could be made even smaller when it would be build straight from the official Alpine Linux Docker image, as it may not be necessary to install all the dependencies that the official Python Dockerfile adds.

eine commented 4 years ago

Images at https://hub.docker.com/u/btdi can be used as a reference. btdi/sphinx:* images are based on Alpine and btdi/latex is based on Debian Buster. Sources are available at https://github.com/buildthedocs/btd/tree/master/images

tk0miya commented 4 years ago

I agree with my image is too fat. I prefer to use debian-slim for the base image because we'll install TeXLive to build PDF.

eine commented 4 years ago

I agree with my image is too fat. I prefer to use debian-slim for the base image because we'll install TeXLive to build PDF.

AFAIK, texlive is not a dependency of Sphinx, and it is not required even for generating latex sources. Texlive is only required to generate a PDF from latex sources, which is completely independent from Sphinx.

Hence, while using Debian slim images for texlive is sensible, I would strongly suggest to make the base image (the one that contains Sphinx) on Alpine.

It is up to the user to execute both images one after the other https://github.com/eine/ghdl/blob/3c873d409f03951a8250408a65c94587f05235d3/doc/make.sh#L34-L51

tk0miya commented 4 years ago

Personally, I got troubles in glibc problems with alpine images. So I hesitate to use them.

eine commented 4 years ago

I'd like to know which packages had issues on Alpine. It does not sound strange to me, but ATM I cannot remember off the top of my head...

tk0miya commented 4 years ago

Sorry, I can't remember well. But it was related with glibc. I found some troubles in Java, Golang and other tools with alpine's libmusl. Indeed, it might not be trouble in running Sphinx. But I'm worry about some extensions might be crashed.

eine commented 4 years ago

If that is the case, I think the sensible approach is to provide alpine and buster variants.

polyzen commented 4 years ago

I've been using https://gitlab.com/paddy-hack/sphinx, but official Docker images would be great too.

tk0miya commented 4 years ago

Now official docker images are available:

Remaining task is updating document.

tk0miya commented 4 years ago

Note: I found another article about alpine and python. I did not confirm its truth. But I'd not like to provide alpine image as official one. https://pythonspeed.com/articles/alpine-docker-python/

tk0miya commented 4 years ago

Done in #7227. Thanks,