Merge pull request #864 from comic/fix_docs

Adds docs requirements file (#795)
comic · Jul 31, 2019 · 62a027f · 62a027f
2 parents 8fab671 + 5d90857
commit 62a027f
Show file tree

Hide file tree

Showing 8 changed files with 219 additions and 20 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,17 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt
diff --git a/Makefile b/Makefile
@@ -32,3 +32,7 @@ push: push_web push_http
 
 migrations:
 	docker-compose run -u $(USER_ID) --rm web python manage.py makemigrations
+
+.PHONY: docs
+docs:
+	docker-compose run --rm -v `pwd`/docs:/docs -u $(USER_ID) web bash -c "cd /docs && make html"
diff --git a/Pipfile b/Pipfile
@@ -16,6 +16,7 @@ pyupgrade = "*"
 pytest-xdist = "*"
 sphinx-autodoc-typehints = "*"
 werkzeug = "*"
+sphinx-rtd-theme = "*"
 
 [packages]
 "beautifulsoup4" = "*"

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/conf.py b/docs/conf.py
@@ -45,6 +45,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
+    "sphinx_rtd_theme",
 ]
 
 napoleon_google_docstring = False
@@ -101,7 +102,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -37,7 +37,7 @@ If you need to manually restart the process you can do this when running ``cycle
 you can also kill the server with ``CTRL+C``.
 
 Windows
-```````
+~~~~~~~
 
 Running Grand-Challenge within a Windows environment requires additional steps before invoking the ``cycle_docker_compose.sh`` script.
 
@@ -195,6 +195,12 @@ Creating Migrations
 If you change a ``models.py`` file then you will need to make the corresponding migration files.
 You can do this with
 
+.. code-block:: console
+
+    $ make migrations
+
+or, more explicitly
+
 .. code-block:: console
 
     $ docker-compose run --rm --user `id -u` web python manage.py makemigrations
@@ -203,18 +209,32 @@ You can do this with
 add these to git and commit.
 
 
-Building the docs
------------------
+Building the documentation
+--------------------------
+
+Using docker
+~~~~~~~~~~~~
+
+Having built the web container with ``cycle_docker_compose.sh`` you can use this to generate the docs with
 
-To build the docs you need to install the environment on your local machine, we use pipenv for this.
+.. code-block:: console
+
+    $ make docs
+
+This will create the docs in the ``docs/_build/html`` directory.
+
+Using pipenv
+~~~~~~~~~~~~
+
+Alternatively, to build the docs locally you need to install the environment on your local machine, we use pipenv for this.
 
 1. Install pipenv
 
 .. code-block:: console
 
     $ pip install pipenv
 
-2. Install the environment from the root of the ``grand-challenge.org`` repo  with
+2. Install the environment from the root of the ``grand-challenge.org`` repo with
 
 .. code-block:: console
 
@@ -228,7 +248,6 @@ To build the docs you need to install the environment on your local machine, we
     $ cd docs
     $ make html
 
-This will create the docs in the ``docs/_build/html`` directory.
 
 
 Adding new dependencies
@@ -260,8 +279,8 @@ The docker compose file included here is for development only.
 If you want to run this in a production environment you will need to make several changes, not limited to:
 
 1. Use ``gunicorn`` rather than run ``runserver_plus`` to run the web process
-1. `Disable mounting of the docker socket <https://docs.docker.com/engine/security/https/>`_
-1. Removing the users that are created by ``init_gc_demo``
+2. `Disable mounting of the docker socket <https://docs.docker.com/engine/security/https/>`_
+3. Removing the users that are created by ``init_gc_demo``
 
 .. _TravisCI: https://travis-ci.org/comic/grand-challenge.org
 .. _Docker: https://docs.docker.com/install/

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,149 @@
+alabaster==0.7.12
+amqp==2.5.0
+apipkg==1.5
+appdirs==1.4.3
+argh==0.26.2
+atomicwrites==1.3.0
+attrs==19.1.0
+Babel==2.7.0
+beautifulsoup4==4.8.0
+billiard==3.6.0.0
+black==19.3b0
+bleach==3.1.0
+boto3==1.9.198
+botocore==1.12.198
+Brotli==1.0.7
+celery==4.3.0
+certifi==2019.6.16
+cffi==1.12.3
+chardet==3.0.4
+Click==7.0
+coverage==4.5.4
+cycler==0.10.0
+decorator==4.4.0
+defusedxml==0.6.0
+Django==2.2.3
+django-appconf==1.0.3
+django-autocomplete-light==3.4.1
+django-celery-beat==1.5.0
+django-celery-email==2.0.2
+django-celery-results==1.1.2
+django-compat==1.0.15
+django-cors-headers==3.0.2
+django-countries==5.3.3
+django-coverage-plugin==1.6.0
+django-crispy-forms==1.7.2
+django-debug-toolbar==2.0
+django-extensions==2.2.1
+django-favicon-plus==0.0.8
+django-guardian==2.0.0
+django-select2==7.1.0
+django-simple-history==2.7.3
+django-storages==1.7.1
+django-summernote==0.8.11.4
+django-timezone-field==3.0
+django-userena-ce==4.1.1
+djangorestframework==3.10.2
+djangorestframework-guardian==0.2.0
+docker==4.0.2
+docutils==0.14
+easy-thumbnails==2.6
+entrypoints==0.3
+execnet==1.6.1
+factory-boy==2.12.0
+Faker==2.0.0
+gunicorn==19.9.0
+html2text==2018.1.9
+httplib2==0.13.1
+idna==2.8
+imagesize==1.1.0
+importlib-metadata==0.19
+ipython-genutils==0.2.0
+Jinja2==2.10.1
+jmespath==0.9.4
+jsonschema==3.0.1
+jupyter-core==4.5.0
+kiwisolver==1.1.0
+kombu==4.6.3
+livereload==2.6.1
+MarkupSafe==1.1.1
+matplotlib==3.1.1
+mistune==0.8.4
+more-itertools==7.2.0
+nbconvert==5.5.0
+nbformat==4.4.0
+numpy==1.17.0
+oauth2==1.9.0.post1
+oauthlib==3.0.2
+packaging==19.1
+pandocfilters==1.4.2
+pathtools==0.1.2
+Pillow==6.1.0
+pipenv==2018.11.26
+pluggy==0.12.0
+port-for==0.3.1
+psycopg2==2.8.3
+py==1.8.0
+pycparser==2.19
+Pygments==2.4.2
+PyJWT==1.7.1
+pyparsing==2.4.2
+pyrsistent==0.15.4
+pytest==5.0.1
+pytest-cov==2.7.1
+pytest-django==3.5.1
+pytest-forked==1.0.2
+pytest-mock==1.10.4
+pytest-xdist==1.29.0
+python-crontab==2.3.8
+python-dateutil==2.8.0
+python-magic==0.4.15
+python-memcached==1.59
+python3-openid==3.1.0
+pytz==2019.1
+pyupgrade==1.21.0
+pyvips==2.1.8
+PyYAML==5.1.1
+redis==3.3.2
+requests==2.22.0
+requests-file==1.4.3
+requests-oauthlib==1.2.0
+s3transfer==0.2.1
+sentry-sdk==0.10.2
+SimpleITK==1.2.0
+six==1.12.0
+snowballstemmer==1.9.0
+social-auth-app-django==3.1.0
+social-auth-core==3.2.0
+sorl-thumbnail==12.5.0
+soupsieve==1.9.2
+Sphinx==2.1.2
+sphinx-autobuild==0.7.1
+sphinx-autodoc-typehints==1.7.0
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.1
+sphinxcontrib-devhelp==1.0.1
+sphinxcontrib-htmlhelp==1.0.2
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.2
+sphinxcontrib-serializinghtml==1.1.3
+sqlparse==0.3.0
+testpath==0.4.2
+text-unidecode==1.2
+tifffile==2019.1.4
+tldextract==2.2.1
+tokenize-rt==3.2.0
+toml==0.10.0
+tornado==6.0.3
+traitlets==4.3.2
+urllib3==1.25.3
+vine==1.3.0
+virtualenv==16.7.2
+virtualenv-clone==0.5.3
+watchdog==0.9.0
+wcwidth==0.1.7
+webencodings==0.5.1
+websocket-client==0.56.0
+Werkzeug==0.15.5
+whitenoise==4.1.3
+zipp==0.5.2
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,3 +1,3 @@
 [tool.black]
 line-length = 79
-target-version = ['py36']
+target-version = ['py37']