From 8fa80c15894da57131cea00f8274737d37d8054f Mon Sep 17 00:00:00 2001 From: kaiyou Date: Tue, 16 Oct 2018 22:52:21 +0200 Subject: [PATCH 1/4] Support multiple docs versions --- docs/Dockerfile | 6 +++++- docs/_templates/page.html | 4 ---- docs/_templates/versions.html | 16 ++++++++++++++++ docs/conf.py | 8 +++++++- docs/docker-compose.yml | 21 +++++++++++++++++++++ 5 files changed, 49 insertions(+), 6 deletions(-) delete mode 100644 docs/_templates/page.html create mode 100644 docs/_templates/versions.html create mode 100644 docs/docker-compose.yml diff --git a/docs/Dockerfile b/docs/Dockerfile index af481a27..c1992f32 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -2,6 +2,9 @@ FROM python:3-alpine COPY requirements.txt /requirements.txt +ARG version=master +ENV VERSION=$version + RUN pip install -r /requirements.txt \ && apk add --no-cache nginx \ && mkdir /run/nginx @@ -9,6 +12,7 @@ RUN pip install -r /requirements.txt \ COPY ./nginx.conf /etc/nginx/conf.d/default.conf COPY . /docs -RUN sphinx-build /docs /build +RUN mkdir -p /build/$VERSION \ + && sphinx-build /docs /build/$VERSION CMD nginx -g "daemon off;" \ No newline at end of file diff --git a/docs/_templates/page.html b/docs/_templates/page.html deleted file mode 100644 index 97296793..00000000 --- a/docs/_templates/page.html +++ /dev/null @@ -1,4 +0,0 @@ -{%- extends "layout.html" %} -{% block body %} - {{ body|replace("VERSION_TAG", version) }} -{% endblock %} diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000..db4d332d --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,16 @@ +
+ + Versions + v: {{ version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+
+
+ diff --git a/docs/conf.py b/docs/conf.py index f89b39fd..e86a7b9e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,6 +2,8 @@ # -*- coding: utf-8 -*- # +import os + extensions = ['sphinx.ext.imgmath', 'sphinx.ext.viewcode'] templates_path = ['_templates'] source_suffix = '.rst' @@ -33,6 +35,10 @@ html_context = { 'display_github': True, 'github_user': 'mailu', 'github_repo': 'mailu', - 'github_version': 'master', + 'github_version': os.environ.get('VERSION', 'master'), + 'versions': [ + ('1.5', '/1.5/'), + ('master', '/master/') + ], 'conf_py_path': '/docs/' } diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml new file mode 100644 index 00000000..0caaa7a4 --- /dev/null +++ b/docs/docker-compose.yml @@ -0,0 +1,21 @@ +version: '3' + + +services: + docs_master: + image: mailu/docs:master + labels: + - traefik.enable=true + - traefik.port=80 + - traefik.main.frontend.rule=Host:${hostname};PathPrefix:/master/ + + docs_15: + image: mailu/docs:1.5 + labels: + - traefik.enable=true + - traefik.port=80 + - traefik.root.frontend.redirect.regex=.* + - traefik.root.frontend.redirect.replacement=/1.5/ + - traefik.root.frontend.rule=Host:${hostname};PathPrefix:/ + - traefik.main.frontend.rule=Host:${hostname};PathPrefix:/1.5/ + From 13e3862ca701f5ec5d5e2f3cbb1fff196f0220ca Mon Sep 17 00:00:00 2001 From: kaiyou Date: Tue, 16 Oct 2018 22:55:05 +0200 Subject: [PATCH 2/4] Simplify the docs configuration --- docs/_templates/layout.html | 2 -- docs/conf.py | 6 +++--- 2 files changed, 3 insertions(+), 5 deletions(-) delete mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index 3f424a0a..00000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,2 +0,0 @@ -{% set version=github_version %} -{% extends "!layout.html" %} diff --git a/docs/conf.py b/docs/conf.py index e86a7b9e..4ac9de3d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,9 +11,9 @@ master_doc = 'index' project = 'Mailu' copyright = '2018, Mailu authors' author = 'Mailu authors' -version = release = 'latest' +version = release = os.environ.get('VERSION', 'master') language = None -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'Dockerfile', 'docker-compose.yml'] pygments_style = 'sphinx' todo_include_todos = False html_theme = 'sphinx_rtd_theme' @@ -35,7 +35,7 @@ html_context = { 'display_github': True, 'github_user': 'mailu', 'github_repo': 'mailu', - 'github_version': os.environ.get('VERSION', 'master'), + 'github_version': version, 'versions': [ ('1.5', '/1.5/'), ('master', '/master/') From 53b9c031c99ccb6c2530cacc8c54a57f92f82a58 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Tue, 16 Oct 2018 23:19:48 +0200 Subject: [PATCH 3/4] Add a warning banner when not reading the stable docs --- docs/_templates/layout.html | 9 +++++++++ docs/conf.py | 1 + 2 files changed, 10 insertions(+) create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..63db07e2 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,9 @@ +{% extends "!layout.html" %} +{% block document %} +{% if version != stable_version %} +
+

You are currently browsing documentation for the {{ version }} branch. Documentation for the stable {{ stable_version }} branch can be found here.

+
+{% endif %} +{{ super() }} +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 4ac9de3d..64997eb1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ html_context = { 'github_user': 'mailu', 'github_repo': 'mailu', 'github_version': version, + 'stable_version': '1.5', 'versions': [ ('1.5', '/1.5/'), ('master', '/master/') From 4ccefd6d5e013ace4d8a27b6af4a26074d15b672 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20M=C3=B6hlmann?= Date: Fri, 19 Oct 2018 13:43:09 +0300 Subject: [PATCH 4/4] Documentation update on local docs container --- docs/contributors/environment.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributors/environment.rst b/docs/contributors/environment.rst index a1cce193..af610c27 100644 --- a/docs/contributors/environment.rst +++ b/docs/contributors/environment.rst @@ -101,7 +101,8 @@ Documentation is maintained in the ``docs`` directory and are maintained as `reS docker build -t docs docs docker run -p 127.0.0.1:8080:80 docs -You can now read the local documentation by navigating to http://localhost:8080. +In a local build Docker always assumes the version to be master. +You can read the local documentation by navigating to http://localhost:8080/master. .. note:: After modifying the documentation, the image needs to be rebuild and the container restarted for the changes to become visible.