Merge pull request #608 from Mailu/feat-docs-docker

Docs as a Docker image

docs/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3-alpine
+
+COPY requirements.txt /requirements.txt
+
+RUN pip install -r /requirements.txt \
+ && apk add --no-cache nginx \
+ && mkdir /run/nginx
+
+COPY ./nginx.conf /etc/nginx/conf.d/default.conf
+COPY . /docs
+
+RUN sphinx-build /docs /build
+
+CMD nginx -g "daemon off;"

docs/conf.py

@@ -7,7 +7,7 @@ templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'Mailu'
-copyright = '2017, Mailu authors'
+copyright = '2018, Mailu authors'
 author = 'Mailu authors'
 version = release = 'latest'
 language = None
@@ -23,7 +23,7 @@ htmlhelp_basename = 'Mailudoc'
 # to template names.
 html_sidebars = {
     '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
+        'relations.html', 
         'searchbox.html',
     ]
 }
@@ -36,24 +36,3 @@ html_context = {
     'github_version': 'master',
     'conf_py_path': '/docs/'
 }
-
-
-# Upload function when the script is called directly
-if __name__ == "__main__":
-    import os, sys, paramiko
-    build_dir, hostname, username, password, dest_dir = sys.argv[1:]
-    transport = paramiko.Transport((hostname, 22))
-    transport.connect(username=username, password=password)
-    sftp = paramiko.SFTPClient.from_transport(transport)
-    os.chdir(build_dir)
-    for dirpath, dirnames, filenames in os.walk("."):
-        remote_path = os.path.join(dest_dir, dirpath)
-        try:
-            sftp.mkdir(remote_path)
-        except:
-            pass
-        for filename in filenames:
-            sftp.put(
-                os.path.join(dirpath, filename),
-                os.path.join(remote_path, filename)
-            )

docs/contributors/environment.rst

@@ -89,3 +89,20 @@ Any change to the files will automatically restart the Web server and reload the
 
 When using the development environment, a debugging toolbar is displayed on the right side
 of the screen, that you can open to access query details, internal variables, etc.
+
+Documentation
+-------------
+
+Documentation is maintained in the ``docs`` directory and are maintained as `reStructuredText`_ files. It is possible to run a local documentation server for reviewing purposes, using Docker:
+
+.. code-block:: bash
+
+  cd <Mailu repo>
+  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.
+
+.. note:: After modifying the documentation, the image needs to be rebuild and the container restarted for the changes to become visible.
+
+.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html

docs/nginx.conf

@@ -0,0 +1,5 @@
+server {
+    listen 80;
+    listen [::]:80;
+    root /build;
+}

docs/requirements.txt

@@ -2,5 +2,3 @@ recommonmark
 Sphinx
 sphinx-autobuild
 sphinx-rtd-theme
-sphinxcontrib-versioning
-paramiko

tests/build.yml

@@ -45,3 +45,7 @@ services:
   none:
     image: mailu/none:$VERSION
     build: ../core/none
+
+  docs:
+    image: mailu/docs:$VERSION
+    build: ../docs