Build documentation in CI

.github/workflows/documentation.yml

@@ -0,0 +1,54 @@
+---
+
+# -------------------------------------------------------------------------------------------------
+# Job Name
+# -------------------------------------------------------------------------------------------------
+name: Docs
+
+
+# -------------------------------------------------------------------------------------------------
+# When to run
+# -------------------------------------------------------------------------------------------------
+on:
+  # Runs on Pull Requests
+  pull_request:
+
+  # Runs on master Branch and Tags
+  push:
+    branches:
+      - master
+    tags:
+
+
+# -------------------------------------------------------------------------------------------------
+# What to run
+# -------------------------------------------------------------------------------------------------
+jobs:
+  docs:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - build
+          - linkcheck
+          - linkcheck2
+
+    name: "[Docs ${{ matrix.target }}]"
+    steps:
+
+      # ------------------------------------------------------------
+      # Checkout repository
+      # ------------------------------------------------------------
+      - name: Checkout repository
+        uses: actions/checkout@v1
+
+      - name: Check documentation
+        shell: bash
+        run: |
+          cd docs
+          make ${TARGET}
+        env:
+          TARGET: ${{ matrix.target }}

.gitignore

@@ -121,6 +121,7 @@
 /docs/_build/
 /docs/make.bat
 /docs/linkcheck
+/docs/venv
 *.rst.todo
 
 # Ignore vhost-gen files in test dir (copied on the fly)

.travis.yml

@@ -30,7 +30,9 @@ env:
   ###
   ### Check Documentation
   ###
-  - S1=DOCUMENTATION
+  - S1=DOCUMENTATION V1=Build
+  - S1=DOCUMENTATION V1=linkcheck
+  - S1=DOCUMENTATION V1=linkcheck2
 
   ###
   ### Check Update script
@@ -222,6 +224,11 @@ env:
   - S1=PHP V1=7.2 S2=MONGO V2=4.2
 
 
+jobs:
+  allow_failures:
+    - env: S1=DOCUMENTATION V1=linkcheck2
+
+
 ###
 ### Installation
 ###
@@ -231,14 +238,6 @@ install:
       until sudo apt-get update -qq; do sleep 5; done
     fi
 
-  # Install dependencies for documentation
-  - if [ "${S1}" = "DOCUMENTATION" ]; then
-      until pip install sphinx; do sleep 5; done;
-      until pip install sphinx-autobuild; do sleep 5; done;
-      until pip install recommonmark; do sleep 5; done;
-      until pip install sphinx_rtd_theme; do sleep 5; done;
-    fi
-
   # Determine latest Docker version in apt
   - DOCKER_APT="";
     if [ "${S1}" = "DOCKER" ]; then
@@ -265,6 +264,18 @@ install:
       sudo mv -f docker-compose /usr/local/bin;
     fi
 
+  # Provide retry function
+  - retry() {
+      for ((n=0; n<60; n++)); do
+        echo "[${n}] ${*}";
+        if eval "${*}"; then
+          return 0;
+        fi;
+        sleep 1;
+      done;
+      return 1;
+    }
+
 
 ###
 ### Before Script
@@ -283,13 +294,6 @@ before_script:
   - sudo service docker stop  || true
   - sudo service docker start || true
 
-  # Show Python/pip
-  - if [ "${S1}" = "DOCUMENTATION" ]; then
-      pip freeze;
-      pip --version;
-      python --version;
-    fi
-
   # Show Docker/Docker Compose
   - if [ "${S1}" != "DOCUMENTATION" ]; then
       docker --version;
@@ -301,34 +305,65 @@ before_script:
 ### Test
 ###
 script:
+
+  ###
+  ### Test Modules
+  ###
   - if [ "${S1}" = "MODULES" ]; then
       cd .tests/;
-      make update-readme;
+      retry make update-readme;
-      git diff --quiet || { echo "Build Changes"; git diff; git status; false; }
+    fi
-    elif [ "${S1}" = "DOCUMENTATION" ]; then
+  - if [ "${S1}" = "MODULES" ]; then
-      cd docs/;
+      git diff --quiet || { echo "Build Changes"; git diff; git status; false; };
-      make build;
+    fi
-      make linkcheck;
+
-      make linkcheck2;
+  ###
-    elif [ "${S1}" = "UPDATE" ]; then
+  ### Test Documentation
-      ./update-docker.sh "${V1}";
+  ###
-    else
+  - if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "Build" ]; then
-      cd .tests/;
+      cd docs/;
-      if [ "${S1}" != "DOCKER" ]; then
+      retry make build;
-        make configure KEY="${S1}_SERVER" VAL="${V1}";
+    fi
-        make configure KEY="${S2}_SERVER" VAL="${V2}";
+  - if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "linkcheck" ]; then
-      fi;
+      cd docs/;
-      make start;
+      retry make linkcheck;
-      make test-smoke-modules;
+    fi
-      make test-smoke-config;
+  - if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "linkcheck2" ]; then
-      make test-smoke-intranet;
+      cd docs/;
-      make test-smoke-vendors;
+      retry make linkcheck2;
-      make test-smoke-vhosts;
+    fi
-      make test-smoke-rproxies;
+
-      make test-smoke-ssl;
+  ###
-      make test-smoke-bind;
+  ### Test Update script
-      make test-smoke-autostart;
+  ###
-      make test-smoke-framework-cakephp;
+  - if [ "${S1}" = "UPDATE" ]; then
-      make test-smoke-framework-drupal;
+      ./update-docker.sh "${V1}";
-      make test-smoke-framework-wordpress;
+    fi
+
+  ###
+  ### Test Devilbox
+  ###
+  - if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
+      cd .tests/;
+    fi
+  - if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
+      if [ "${S1}" != "DOCKER" ]; then
+        retry make configure KEY="${S1}_SERVER" VAL="${V1}";
+        retry make configure KEY="${S2}_SERVER" VAL="${V2}";
+      fi
+    fi
+  - if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
+      retry make start;
+      retry make test-smoke-modules;
+      retry make test-smoke-config;
+      retry make test-smoke-intranet;
+      retry make test-smoke-vendors;
+      retry make test-smoke-vhosts;
+      retry make test-smoke-rproxies;
+      retry make test-smoke-ssl;
+      retry make test-smoke-bind;
+      retry make test-smoke-autostart;
+      retry make test-smoke-framework-cakephp;
+      retry make test-smoke-framework-drupal;
+      retry make test-smoke-framework-wordpress;
     fi

README.md

@@ -26,6 +26,7 @@
 [![License](https://img.shields.io/badge/license-MIT-%233DA639.svg)](https://opensource.org/licenses/MIT)
 
 [![Build Status](https://github.com/cytopia/devilbox/workflows/Lint/badge.svg)](https://github.com/cytopia/devilbox/actions?workflow=Lint)
+[![Build Status](https://github.com/cytopia/devilbox/workflows/Docs/badge.svg)](https://github.com/cytopia/devilbox/actions?workflow=Docs)
 [![Build Status](https://github.com/cytopia/devilbox/workflows/Linux/badge.svg)](https://github.com/cytopia/devilbox/actions?workflow=Linux)
 [![Build Status](https://github.com/cytopia/devilbox/workflows/Config/badge.svg)](https://github.com/cytopia/devilbox/actions?workflow=Config)
 [![Build Status](https://github.com/cytopia/devilbox/workflows/Versions/badge.svg)](https://github.com/cytopia/devilbox/actions?workflow=Versions)

docs/Makefile

@@ -1,52 +1,27 @@
-# Minimal makefile for Sphinx documentation
+ifneq (,)
-#
+.error This Makefile requires GNU Make.
+endif
 
-# You can set these variables from the command line.
+# -------------------------------------------------------------------------------------------------
-SPHINXOPTS    =
+# Default configuration
-SPHINXBUILD   = sphinx-build
+# -------------------------------------------------------------------------------------------------
-SPHINXPROJ    = devilbox
+.PHONY: help build autobuild linkcheck linkcheck2
-SOURCEDIR     = .
+
-BUILDDIR      = _build
+
+# -------------------------------------------------------------------------------------------------
+# Default Target
+# -------------------------------------------------------------------------------------------------
 
-# Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo
-	@echo "Devilbox additional commands:"
 	@echo "build            Build and test documentation"
-	@echo "  autobuild   Continuously run and build (http://127.0.0.1:8000)"
+	@echo "autobuild        Continuously run and build (http://0.0.0.0:8000)"
-
+	@echo "linkcheck        Sphinx linkcheck"
-.PHONY: help Makefile test build autobuild
+	@echo "linkcheck2       Custom linkcheck"
-
-# 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)
 
 
-#
+# -------------------------------------------------------------------------------------------------
-# Devilbox additions
+#  Target
-#
+# -------------------------------------------------------------------------------------------------
-#
-# Used Sphinx options:
-# --------------------
-#
-# -a: Always write all output files. The default is to only write output files
-#     for new and changed source files.
-#
-# -E: Don’t use a saved environment (the structure caching all cross-references),
-#     but rebuild it completely.
-#
-# -n: Run in nit-picky mode. Currently, this generates warnings for all
-#     missing references. See the config value nitpick_ignore for a way to
-#     exclude some references as “known missing”.
-#
-# -q: Do not output anything on standard output, only write warnings and errors
-#     to standard error.
-#
-# -W: Turn warnings into errors. This means that the build stops at the first
-#     warning and sphinx-build exits with exit status 1.
-
 
 linkcheck2:
 ifeq ($(wildcard file1),)
@@ -57,8 +32,39 @@ endif
 	chmod +x linkcheck
 	./linkcheck -l -k -r 60 -t 30 -e rst _includes/
 
+linkcheck:
+	docker run \
+		--rm \
+		$$(tty -s && echo "-it" || echo) \
+		-e SPHINX_PROJECT="docs" \
+		-e SPHINX_PORT=8000 \
+		-e NEW_UID="$$(id -u)" \
+		-e NEW_GID="$$(id -g)" \
+		-v $(PWD)/..:/shared/httpd \
+		devilbox/python-sphinx:3.8-dev \
+		sphinx-build -M linkcheck . _build
+
 build:
-	sphinx-build -a -E -n -j auto -q -W . _build/html
+	docker run \
+		--rm \
+		$$(tty -s && echo "-it" || echo) \
+		-e SPHINX_PROJECT="docs" \
+		-e SPHINX_PORT=8000 \
+		-e NEW_UID="$$(id -u)" \
+		-e NEW_GID="$$(id -g)" \
+		-v $(PWD)/..:/shared/httpd \
+		devilbox/python-sphinx:3.8-dev \
+		sphinx-build -a -E -n -j auto -W . _build/html
 
 autobuild:
-	sphinx-autobuild . _build/html
+	docker run \
+		--rm \
+		$$(tty -s && echo "-it" || echo) \
+		-e SPHINX_PROJECT="docs" \
+		-e SPHINX_PORT=8000 \
+		-e NEW_UID="$$(id -u)" \
+		-e NEW_GID="$$(id -g)" \
+		-p "8000:8000" \
+		-v $(PWD)/..:/shared/httpd \
+		devilbox/python-sphinx:3.8-dev \
+		sphinx-autobuild -a -E -n -j auto -W -H 0.0.0.0 -p 8000 . _build/html

docs/README.md

@@ -19,10 +19,15 @@ You can also build the documentation locally before pushing to ensure everything
 
 #### Requirements
 
+* Docker
+
+#### How to check for broken links
 ```
-sudo pip install sphinx sphinx-autobuild recommonmark
+cd docs/
-sudo pip install sphinx_rtd_theme
+make linkcheck
+make linkcheck2
 ```
+
 #### How to build and error-check
 ```
 cd docs/
@@ -37,4 +42,4 @@ make autobuild
 
 #### How to view
 
-When using `make autobuild` your documentation is served at: http://127.0.0.1:8000
+When using `make autobuild` your documentation is served at: http://0.0.0.0:8000

docs/conf.py

@@ -78,6 +78,8 @@ language = None
 exclude_patterns = [
     u'_build/*',
     u'_includes/**',
+    u'venv/**',
+    u'requirements.txt',
     u'Thumbs.db',
     u'.DS_Store'
 ]

docs/requirements.txt

@@ -0,0 +1,2 @@
+recommonmark
+sphinx_rtd_theme