do docs requirements differently

Author: peterbe

Dockerfile.dev

@@ -40,6 +40,12 @@ COPY requirements.txt /tmp/
 WORKDIR /tmp
 RUN pip install --no-cache-dir -r requirements.txt
 
+# Install Python dependencies specifically for building docs
+COPY docs-requirements.txt /tmp/
+# Switch to /tmp to install dependencies outside home dir
+WORKDIR /tmp
+RUN pip install --no-cache-dir -r docs-requirements.txt
+
 # Install frontend dependencies using NPM
 COPY package.json /opt/npm/
 

readthedocs-requirements.txt docs-requirements.txt

@@ -33,6 +33,21 @@ To build the docs, run this:
 
     $ make docs
 
+This is the same as running:
+
+.. code-block:: shell
+
+    $ docker-compose run web ./bin/build_docs.sh
+
+To iterate on writing docs and testing that what you type compiles correctly,
+run the above mentioned command on every save and then open the file
+``docs/_build/html/index.html``. E.g.
+
+.. code-block:: shell
+
+    # the 'open' command is for OSX
+    $ open docs/_build/html/index.html
+
 
 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 

docs/dev.rst

@@ -1,3 +1,3 @@
 python:
   version: 3.5
-requirements_file: readthedocs-requirements.txt
+requirements_file: docs-requirements.txt