Merge pull request #1166 from maykinmedia/feature/2176-docs

[#2176] Set up documentation build with Sphinx

.github/workflows/ci.yml

@@ -144,6 +144,26 @@ jobs:
           DB_PASSWORD: ''
           E2E_DRIVER: ${{ matrix.browser }}
 
+  docs:
+    name: Build and check documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: 'true'
+      - name: Set up backend environment
+        uses: maykinmedia/setup-django-backend@v1
+        with:
+          apt-packages: 'libxml2-dev libxmlsec1-dev libxmlsec1-openssl gettext libgdal-dev gdal-bin'
+          python-version: '3.11'
+          setup-node: 'no'
+
+      - name: Build and test docs
+        run: |
+          export OPENSSL_CONF=$(pwd)/openssl.conf
+          pytest check_sphinx.py -v --tb=auto
+        working-directory: docs
   #
   # Docker
   #

.github/workflows/dependencies.yml

@@ -47,6 +47,9 @@ jobs:
         with:
           python-version: '3.11'
 
+      - name: Install OS-level deps
+        run: brew install postgresql
+
       - name: Install pip-tools
         run: pip install pip-tools
 

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: 'ubuntu-20.04'
+  apt_packages:
+    - libxml2-dev
+    - libxmlsec1-dev
+    - libxmlsec1-openssl
+    - wget
+  tools:
+    python: '3.11'
+
+python:
+  install:
+    - requirements: requirements/ci.txt

bin/compile_dependencies.sh

@@ -32,7 +32,8 @@ pip-compile \
     --output-file requirements/ci.txt \
     "$@" \
     requirements/base.txt \
-    requirements/test-tools.in
+    requirements/test-tools.in \
+    requirements/docs.in
 
 # Dev depedencies - exact same set as CI + some extra tooling
 pip-compile \

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/theme_overrides.css

@@ -0,0 +1,32 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+   .wy-table-responsive table td:first-child {
+      white-space: nowrap !important;
+   }
+   .wy-table-responsive table {
+      background-color: white;
+   }
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+
+/* Depends on logo but default seems ok for this.
+.wy-side-nav-search {
+   background-color: #04A5BB;
+}
+*/
+
+.rst-content a:link, .rst-content a:visited {
+  color: #017092;
+}
+
+.rst-content a:focus, .rst-content a:hover {
+  color: #051F31;
+}

docs/check_sphinx.py

@@ -0,0 +1,17 @@
+import subprocess
+
+
+def test_linkcheck(tmpdir):
+    doctrees = tmpdir.join("doctrees")
+    htmldir = tmpdir.join("html")
+    subprocess.check_call(
+        ["sphinx-build", "-W", "-blinkcheck", "-d", str(doctrees), ".", str(htmldir)],
+    )
+
+
+def test_build_docs(tmpdir):
+    doctrees = tmpdir.join("doctrees")
+    htmldir = tmpdir.join("html")
+    subprocess.check_call(
+        ["sphinx-build", "-W", "-bhtml", "-d", str(doctrees), ".", str(htmldir)],
+    )