From 72da0bfa9cb7897b03a5ebaef3f2ece3d31247db Mon Sep 17 00:00:00 2001 From: Andrew Chen Wang <60190294+Andrew-Chen-Wang@users.noreply.github.com> Date: Wed, 4 Nov 2020 12:17:02 -0500 Subject: [PATCH] Fix docs service and add RTD support (#2920) Co-authored-by: Andrew-Chen-Wang Co-authored-by: Bruno Alla --- docs/document.rst | 19 ++++++++++++++++-- .../.readthedocs.yml | 9 +++++++++ .../compose/local/docs/Dockerfile | 6 ++++-- .../compose/local/docs/start | 7 +++++++ {{cookiecutter.project_slug}}/docs/Makefile | 2 +- {{cookiecutter.project_slug}}/docs/conf.py | 18 ++++++++++++----- .../docs/{_source => }/howto.rst | 0 .../docs/{_source => }/index.rst | 0 .../{_source => }/pycharm/configuration.rst | 0 .../docs/{_source => }/pycharm/images/1.png | Bin .../docs/{_source => }/pycharm/images/2.png | Bin .../docs/{_source => }/pycharm/images/3.png | Bin .../docs/{_source => }/pycharm/images/4.png | Bin .../docs/{_source => }/pycharm/images/7.png | Bin .../docs/{_source => }/pycharm/images/8.png | Bin .../docs/{_source => }/pycharm/images/f1.png | Bin .../docs/{_source => }/pycharm/images/f2.png | Bin .../docs/{_source => }/pycharm/images/f3.png | Bin .../docs/{_source => }/pycharm/images/f4.png | Bin .../{_source => }/pycharm/images/issue1.png | Bin .../{_source => }/pycharm/images/issue2.png | Bin .../docs/{_source => }/users.rst | 0 {{cookiecutter.project_slug}}/local.yml | 3 ++- 23 files changed, 53 insertions(+), 11 deletions(-) create mode 100644 {{cookiecutter.project_slug}}/.readthedocs.yml create mode 100644 {{cookiecutter.project_slug}}/compose/local/docs/start rename {{cookiecutter.project_slug}}/docs/{_source => }/howto.rst (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/index.rst (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/configuration.rst (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/1.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/2.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/3.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/4.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/7.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/8.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/f1.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/f2.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/f3.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/f4.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/issue1.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/pycharm/images/issue2.png (100%) rename {{cookiecutter.project_slug}}/docs/{_source => }/users.rst (100%) diff --git a/docs/document.rst b/docs/document.rst index 15a5396e..a3097909 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/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. +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}}/.readthedocs.yml b/{{cookiecutter.project_slug}}/.readthedocs.yml new file mode 100644 index 00000000..b193a85e --- /dev/null +++ b/{{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 diff --git a/{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile b/{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile index 7736777b..315fdd40 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 00000000..fd2e0de6 --- /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/Makefile b/{{cookiecutter.project_slug}}/docs/Makefile index 4f772cad..0b56e1f8 100644 --- a/{{cookiecutter.project_slug}}/docs/Makefile +++ b/{{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 diff --git a/{{cookiecutter.project_slug}}/docs/conf.py b/{{cookiecutter.project_slug}}/docs/conf.py index 691f351e..c640e1c6 100644 --- a/{{cookiecutter.project_slug}}/docs/conf.py +++ b/{{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() diff --git a/{{cookiecutter.project_slug}}/docs/_source/howto.rst b/{{cookiecutter.project_slug}}/docs/howto.rst similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/howto.rst rename to {{cookiecutter.project_slug}}/docs/howto.rst diff --git a/{{cookiecutter.project_slug}}/docs/_source/index.rst b/{{cookiecutter.project_slug}}/docs/index.rst similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/index.rst rename to {{cookiecutter.project_slug}}/docs/index.rst diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/configuration.rst b/{{cookiecutter.project_slug}}/docs/pycharm/configuration.rst similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/configuration.rst rename to {{cookiecutter.project_slug}}/docs/pycharm/configuration.rst diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/1.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/1.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/1.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/1.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/2.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/2.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/2.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/2.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/3.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/3.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/3.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/3.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/4.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/4.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/4.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/4.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/7.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/7.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/7.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/7.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/8.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/8.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/8.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/8.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/f1.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/f1.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/f1.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/f1.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/f2.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/f2.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/f2.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/f2.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/f3.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/f3.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/f3.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/f3.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/f4.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/f4.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/f4.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/f4.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/issue1.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/issue1.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/issue1.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/issue1.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/pycharm/images/issue2.png b/{{cookiecutter.project_slug}}/docs/pycharm/images/issue2.png similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/pycharm/images/issue2.png rename to {{cookiecutter.project_slug}}/docs/pycharm/images/issue2.png diff --git a/{{cookiecutter.project_slug}}/docs/_source/users.rst b/{{cookiecutter.project_slug}}/docs/users.rst similarity index 100% rename from {{cookiecutter.project_slug}}/docs/_source/users.rst rename to {{cookiecutter.project_slug}}/docs/users.rst diff --git a/{{cookiecutter.project_slug}}/local.yml b/{{cookiecutter.project_slug}}/local.yml index a6cbe543..e285f349 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: