Start using docker-compose and watch the changed files to simplify docs development.

Author: jpjoao

Dockerfile

@@ -1,16 +1,14 @@
 FROM python:2-stretch as builder
 
-WORKDIR /www
-
 COPY ./_build/.requirements.txt _build/
 
 RUN pip install pip==9.0.1 wheel==0.29.0 \
  && pip install -r _build/.requirements.txt
 
-COPY . /www
+EXPOSE 8000
 
-RUN make -C _build html
+VOLUME /www
 
-FROM nginx:latest
+WORKDIR /www/_build
 
-COPY --from=builder /www/_build/html /usr/share/nginx/html
+CMD make html && make livehtml

_build/.requirements.txt

@@ -10,4 +10,5 @@ requests==2.20.0
 six==1.10.0
 snowballstemmer==1.2.1
 sphinx==1.3.6
+sphinx-autobuild==0.6.0
 git+https://github.com/fabpot/sphinx-php.git@v1.0.14#egg_name=sphinx-php

_build/Makefile

@@ -2,10 +2,13 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-BUILDDIR = .
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = .
+SPHINXAUTOBUILD = sphinx-autobuild
+IGNOREWATCH= --ignore "/www/_build" \
+ --ignore "/www/.idea"
 
 # Internal variables.
 PAPEROPT_a4 = -D latex_paper_size=a4
@@ -14,7 +17,7 @@ ALLSPHINXOPTS = -c $(BUILDDIR) -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html livehtml dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 @echo "Please use \`make <target>' where <target> is one of"
@@ -37,6 +40,7 @@ help:
 @echo " changes to make an overview of all changed/added/deprecated items"
 @echo " linkcheck to check all external links for integrity"
 @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+@echo " livehtml to keep recreating the files that are changed"
 
 clean:
 -rm -rf $(BUILDDIR)/*
@@ -151,3 +155,9 @@ doctest:
 $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 @echo "Testing of doctests in the sources finished, look at the " \
  "results in $(BUILDDIR)/doctest/output.txt."
+
+livehtml:
+$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+$(SPHINXAUTOBUILD) --host 0.0.0.0 --port 8000 --watch /www -b html $(ALLSPHINXOPTS) $(IGNOREWATCH) /www/_build/html
+@echo
+@echo "Listening to changes and rebuilding files"

contributing/documentation/overview.rst

@@ -249,21 +249,20 @@ GitHub, click on the **Show all checks** link and finally, click on the
 Build the Documentation Locally
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have Docker installed on your machine, run these commands to build the
-docs:
+If you have Docker installed on your machine, this command will build
+the image, compile the docs, and start to watch for changes and
+automatically compile them:
 
 .. code-block:: terminal
 
- # build the image...
- $ docker build . -t symfony-docs
+ $ docker-compose up
 
- # ...and start the local web server
- # (if it's already in use, change the '8080' port by any other port)
- $ docker run --rm -p 8080:80 symfony-docs
-
-You can now read the docs at ``http://127.0.0.1:8080`` (if you use a virtual
+You can now read the docs at ``http://localhost:8080`` (if you use a virtual
 machine, browse its IP instead of localhost; e.g. ``http://192.168.99.100:8080``).
 
+If por `8080` is already in use, you can change the mapping on `docker-compose.yaml`
+file to any other free port.
+
 If you don't use Docker, follow these steps to build the docs locally:
 
 #. Install `pip`_ as explained in the `pip installation`_ article;

docker-compose.yaml

@@ -0,0 +1,11 @@
+version: '3.3'
+services:
+ symfony-docs:
+ build:
+ context: ./
+ image: symfony-docs:latest
+ user: ${CURRENT_UID}
+ ports:
+ - 8080:8000
+ volumes:
+ - .:/www