feat: add local preview with Docker

Add a Dockerfile and a docker-compose.yml to be able to quickly preview
the document locally using the template at https://github.com/italia/docs-italia-template.

Author: bfabio

.gitignore

@@ -1,3 +1,4 @@
 html/
 .venv
-.vscode
+.vscode
+_build

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.8
+
+WORKDIR /app
+
+COPY preview_build/requirements.txt requirements.txt
+
+RUN pip3 install -r requirements.txt
+
+EXPOSE 8000
+
+CMD [ "sphinx-autobuild", ".", "_build", "--host", "0.0.0.0"]

README.md

@@ -45,11 +45,32 @@ Le funzioni di hosting e di ricerca sono basate su [ReadTheDocs](https://readthe
 
 Tutti i documenti di *Docs Italia* possono essere fruiti anche in formato .epub e .pdf
 
-## Compilazione della documentazione
-I file contenuti in questo repository possono essere modificati sul proprio computer ed essere convertiti in formato HTML per validarne i cambiamenti. È necessario innanzitutto installare il tema di Docs Italia attraverso il seguente comando:
 
-`pip install -r requirements.txt`
+## Dipendenze
 
-Quindi lanciare il comando [Sphinx](http://www.sphinx-doc.org) per validare e generare la documentazione, che sarà consultabile all'indirizzo `./html/index.html`:
+Il repository è strutturato per essere compatibile con [Docs Italia](https://docs.italia.it/).
+La piattaforma accetta documenti in formato RST o MD.
+Per informazioni sulla struttura di questo repository visita il [repository
+dedicato](https://github.com/italia/docs-italia-starter-kit).
 
-`sphinx-build -n -W -T -b html . html`
+## Preview
+
+Per lavorare utilizzando una preview del documento è sufficiente lanciare Docker
+
+```shell
+docker-compose up
+```
+
+la preview sarà visibile all'indirizzo [http://localhost:8000/](http://localhost:8000/)
+
+## Come contribuire
+
+Ogni contributo è benvenuto!
+È possibile aprire delle issue per segnalare errori, problemi o per la
+richiesta di nuove funzionalità.
+Inoltre, è possibile aprire delle Pull Request per proporre direttamente delle
+modifiche.
+
+## Licenza
+
+Questo documento è rilasciato con una licenza CC BY 4.0.

docker-compose.yml

@@ -0,0 +1,10 @@
+version: "3.5"
+services:
+  web:
+    build: .
+    volumes:
+      - .:/app
+      - /app/preview_build/
+      - ./preview_build/preview_configuration.py:/app/conf.py
+    ports:
+      - "8000:8000"

preview_build/build.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+rm -rf ./build && \
+cp ./preview_configuration.py ./conf.py && \
+sphinx-build .. build -c .

preview_build/preview_configuration.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# Sphinx RTD theme demo documentation build configuration file, created by
+# sphinx-quickstart on Sun Nov  3 11:56:36 2013.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+import docs_italia_theme
+
+from os.path import abspath, join, dirname
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.doctest',
+    'docs_italia_theme',
+]
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'docs_italia_theme'
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [docs_italia_theme.get_html_theme_path()]

preview_build/requirements.txt

@@ -0,0 +1,3 @@
+Sphinx==3.4.3
+sphinx-autobuild==2020.9.1
+docs-italia-theme @ git+https://github.com/italia/docs-italia-theme.git