Add RTD support & fix Docker docs

* Set DATABASE_URL environment variable to sqlite inside conf.py instead of the compose file since it's not changed very often.
* Setting the DATABASE_URL to SQLite avoids a dependency on the Postgres service
* Docker docs service should use /start-docs to be consistent with other start commands
* Added RTD configuration file

.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+sphinx:
+  configuration: docs/_source/conf.py
+
+python:
+  version: 3.8
+  install:
+    - requirements: requirements/local.txt

docs/document.rst

@@ -15,6 +15,8 @@ If you set up your project to `develop locally with docker`_, run the following
 
 Navigate to port 7000 on your host to see the documentation. This will be opened automatically at `localhost`_ for local, non-docker development.
 
+Note: using Docker for documentation sets up a temporary SQLite file by setting the environment variable ``DATABASE_URL=sqlite:///readthedocs.db`` in ``docs/_sources/conf.py`` to avoid a dependency on PostgreSQL.
+
 Generate API documentation
 ----------------------------
 
@@ -23,7 +25,20 @@ Edit the ``docs/_source`` files and project application docstrings to create you
 Sphinx can automatically include class and function signatures and docstrings in generated documentation.
 See the generated project documentation for more examples.
 
+Setting up ReadTheDocs
+----------------------
+
+To setup your documentation on `ReadTheDocs`_, you must
+
+1. Go to `ReadTheDocs`_ and login/create an account
+2. Add your GitHub repository
+3. Trigger a build
+
+Additionally, you can auto-build Pull Request previews, but `you must enable it`_.
+
 .. _localhost: http://localhost:7000/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
 .. _develop locally: ./developing-locally.html
 .. _develop locally with docker: ./developing-locally-docker.html
+.. _ReadTheDocs: https://readthedocs.org/
+.. _you must enable it: https://docs.readthedocs.io/en/latest/guides/autobuild-docs-for-pull-requests.html#autobuild-documentation-for-pull-requests

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile

@@ -24,6 +24,8 @@ COPY ./requirements /requirements
 # All imports needed for autodoc.
 RUN pip install -r /requirements/local.txt -r /requirements/production.txt
 
-WORKDIR /docs
+COPY ./compose/local/docs/start /start-docs
+RUN sed -i 's/\r$//g' /start-docs
+RUN chmod +x /start-docs
 
-CMD make livehtml
+WORKDIR /docs

{{cookiecutter.project_slug}}/compose/local/docs/start

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

{{cookiecutter.project_slug}}/docs/_source/conf.py

@@ -14,12 +14,20 @@ import os
 import sys
 import django
 
-{% if cookiecutter.use_docker == 'y' %}
-sys.path.insert(0, os.path.abspath("/app"))
-os.environ.setdefault("DATABASE_URL", "")
-{% else %}
-sys.path.insert(0, os.path.abspath(".."))
+if os.getenv("READTHEDOCS", default=False) == "True":
+    sys.path.insert(0, os.path.abspath("../.."))
+    os.environ["DJANGO_READ_DOT_ENV_FILE"] = "True"
+    {%- if cookiecutter.use_celery == 'y' %}
+    os.environ["CELERY_BROKER_URL"] = os.getenv("REDIS_URL", "redis://redis:6379")
+    {%- endif %}
+    os.environ["USE_DOCKER"] = "no"
+else:
+{%- if cookiecutter.use_docker == 'y' %}
+    sys.path.insert(0, os.path.abspath("/app"))
+{%- else %}
+    sys.path.insert(0, os.path.abspath("../.."))
 {%- endif %}
+os.environ["DATABASE_URL"] = "sqlite:///readthedocs.db"
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.local")
 django.setup()
 

{{cookiecutter.project_slug}}/local.yml

@@ -51,6 +51,7 @@ services:
       - ./{{ cookiecutter.project_slug }}:/app/{{ cookiecutter.project_slug }}:z
     ports:
       - "7000:7000"
+    command: /start-docs
 
   {%- if cookiecutter.use_mailhog == 'y' %}