diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..3f316fdab --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,9 @@ +version: 2 + +sphinx: + configuration: docs/_source/conf.py + +python: + version: 3.8 + install: + - requirements: requirements/local.txt diff --git a/docs/document.rst b/docs/document.rst index 15a5396e1..a6e6b72f4 100644 --- a/docs/document.rst +++ b/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/_sources/conf.py`` to avoid a dependency on PostgreSQL. + Generate API documentation ---------------------------- Edit the ``docs/_source`` files and project application docstrings to create your documentation. -Sphinx can automatically include class and function signatures and docstrings in generated 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 diff --git a/{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile b/{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile index 7736777b3..315fdd405 100644 --- a/{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile +++ b/{{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 diff --git a/{{cookiecutter.project_slug}}/compose/local/docs/start b/{{cookiecutter.project_slug}}/compose/local/docs/start new file mode 100644 index 000000000..fd2e0de6a --- /dev/null +++ b/{{cookiecutter.project_slug}}/compose/local/docs/start @@ -0,0 +1,7 @@ +#!/bin/bash + +set -o errexit +set -o pipefail +set -o nounset + +make livehtml diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/_source/conf.py similarity index 78% rename from {{cookiecutter.project_slug}}/docs/conf.py rename to {{cookiecutter.project_slug}}/docs/_source/conf.py index 691f351e5..3fc411aa6 100644 --- a/{{cookiecutter.project_slug}}/docs/conf.py +++ b/{{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() diff --git a/{{cookiecutter.project_slug}}/local.yml b/{{cookiecutter.project_slug}}/local.yml index a6cbe5430..e285f3498 100644 --- a/{{cookiecutter.project_slug}}/local.yml +++ b/{{cookiecutter.project_slug}}/local.yml @@ -51,7 +51,8 @@ services: - ./{{ cookiecutter.project_slug }}:/app/{{ cookiecutter.project_slug }}:z ports: - "7000:7000" - + command: /start-docs + {%- if cookiecutter.use_mailhog == 'y' %} mailhog: