Add docs service in docker-compose (celery#6894)

* Add docs service in docker-compose

* Add documentation about running the docs with docker

CONTRIBUTING.rst

@@ -710,6 +710,20 @@ After building succeeds, the documentation is available at :file:`_build/html`.
 
 .. _contributing-verify:
 
+Build the documentation using Docker
+------------------------------------
+
+Build the documentation by running:
+
+.. code-block:: console
+
+    $ docker-compose -f docker/docker-compose.yml up --build docs
+
+The service will start a local docs server at ``:7000``. The server is using
+``sphinx-autobuild`` with the ``--watch`` option enabled, so you can live
+edit the documentation. Check the additional options and configs in
+:file:`docker/docker-compose.yml`
+
 Verifying your contribution
 ---------------------------
 

docker/docker-compose.yml

@@ -37,3 +37,14 @@ services:
 
   azurite:
     image: mcr.microsoft.com/azure-storage/azurite:3.10.0
+
+  docs:
+    image: celery/docs
+    build:
+      context: ..
+      dockerfile: docker/docs/Dockerfile
+    volumes:
+        - ../docs:/docs:z
+    ports:
+      - "7000:7000"
+    command: /start-docs

docker/docs/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.9-slim-buster
+
+ENV PYTHONUNBUFFERED 1
+ENV PYTHONDONTWRITEBYTECODE 1
+
+RUN apt-get update \
+    # dependencies for building Python packages
+    && apt-get install -y build-essential \
+    && apt-get install -y texlive \
+    && apt-get install -y texlive-latex-extra \
+    && apt-get install -y dvipng \
+    && apt-get install -y python3-sphinx \
+    # Translations dependencies
+    && apt-get install -y gettext \
+    # cleaning up unused files
+    && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
+    && rm -rf /var/lib/apt/lists/*
+
+# # Requirements are installed here to ensure they will be cached.
+COPY /requirements /requirements
+
+# All imports needed for autodoc.
+RUN pip install -r /requirements/docs.txt -r /requirements/default.txt
+
+COPY docker/docs/start /start-docs
+RUN sed -i 's/\r$//g' /start-docs
+RUN chmod +x /start-docs
+
+WORKDIR /docs

docker/docs/start

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+
+make livehtml

docs/Makefile

@@ -6,6 +6,8 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+SOURCEDIR     = .
+APP 		  = /docs
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -18,6 +20,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  livehtml   to start a local server hosting the docs"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -231,3 +234,7 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: livehtml
+livehtml:
+	sphinx-autobuild -b html --host 0.0.0.0 --port 7000 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html

docs/make.bat

@@ -19,6 +19,7 @@ if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
 	echo.  html       to make standalone HTML files
+	echo.  livehtml   to start a local server hosting the docs
 	echo.  dirhtml    to make HTML files named index.html in directories
 	echo.  singlehtml to make a single large HTML file
 	echo.  pickle     to make pickle files
@@ -269,4 +270,9 @@ if "%1" == "pseudoxml" (
 	goto end
 )
 
+if "%1" == "livehtml" (
+	sphinx-autobuild -b html --open-browser -p 7000 --watch %APP% -c . %SOURCEDIR% %BUILDDIR%/html
+	goto end
+)
+
 :end

requirements/docs.txt

@@ -6,3 +6,4 @@ sphinx-click==2.5.0
 -r test.txt
 -r deps/mock.txt
 -r extras/auth.txt
+-r extras/sphinxautobuild.txt

requirements/extras/sphinxautobuild.txt

@@ -0,0 +1 @@
+sphinx-autobuild>=2021.3.14