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>
This commit is contained in:
Andrew Chen Wang 2020-11-04 12:17:02 -05:00 committed by GitHub
parent 702455059f
commit 72da0bfa9c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 53 additions and 11 deletions

View File

@ -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

View File

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

View File

@ -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

View File

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

View File

@ -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

View File

@ -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()

View File

Before

Width:  |  Height:  |  Size: 66 KiB

After

Width:  |  Height:  |  Size: 66 KiB

View File

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

View File

Before

Width:  |  Height:  |  Size: 177 KiB

After

Width:  |  Height:  |  Size: 177 KiB

View File

Before

Width:  |  Height:  |  Size: 110 KiB

After

Width:  |  Height:  |  Size: 110 KiB

View File

Before

Width:  |  Height:  |  Size: 6.1 KiB

After

Width:  |  Height:  |  Size: 6.1 KiB

View File

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

View File

Before

Width:  |  Height:  |  Size: 249 KiB

After

Width:  |  Height:  |  Size: 249 KiB

View File

Before

Width:  |  Height:  |  Size: 229 KiB

After

Width:  |  Height:  |  Size: 229 KiB

View File

Before

Width:  |  Height:  |  Size: 230 KiB

After

Width:  |  Height:  |  Size: 230 KiB

View File

Before

Width:  |  Height:  |  Size: 222 KiB

After

Width:  |  Height:  |  Size: 222 KiB

View File

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

View File

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

View File

@ -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: