Fix docs service and add RTD support (#2920)

Co-authored-by: Andrew-Chen-Wang <Andrew-Chen-Wang@users.noreply.github.com>
Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

docs/document.rst

@@ -15,15 +15,30 @@ 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/conf.py`` to avoid a dependency on PostgreSQL.
+
 Generate API documentation
 ----------------------------
 
-Edit the ``docs/_source`` files and project application docstrings to create your documentation.
+Edit the ``docs`` files and project application docstrings to create your documentation.
 
 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}}/.readthedocs.yml

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

{{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/Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?= 
 SPHINXBUILD   ?= sphinx-build -c .
-SOURCEDIR     = ./_source
+SOURCEDIR     = .
 BUILDDIR      = ./_build
 {%- if cookiecutter.use_docker == 'y' %}
 APP = /app

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

@@ -14,11 +14,19 @@ 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"
+    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"
+{%- if cookiecutter.use_celery == 'y' %}
+os.environ["CELERY_BROKER_URL"] = os.getenv("REDIS_URL", "redis://redis:6379")
 {%- endif %}
 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' %}