Merge branch 'update-sphinx' into 'master'

Update sphinx

See merge request !8

README.md

@@ -14,8 +14,17 @@ The first command only builds English. The second builds all translations
 (and takes longer).
 
 ```
+  # build/update the dockerized manual builder
+  manual-build/build-builder.sh
+
+  # build english manual for current branch
   manual-build/build-manual.sh TRANSLATIONS=en html
+  # build all translations for current branch
   manual-build/build-manual.sh html
+
+  manual-build/local-server.sh start
+  # check your changes in site served from the local server
+  manual-build/local-server.sh stop
 ```
 
 The built docs will be in the `build/html` directory (on your host machine).
@@ -41,10 +50,12 @@ you continue.
 If docker is available you can build the docbuilder image on Linux with:
 
 ```
-cd manual-build
-docker build --build-arg IMAGE_UID=`id -u` --build-arg IMAGE_GID=`id -g` --tag mahara/docbuilder .
+./manual-build/build-builder.sh
 ```
 
+Note: this command should be run periodically to freshen up (patch) the builder
+image.
+
 The `mahara/docbuilder` image is based on a debian docker image with additional
 packages that are required for building the docs installed. Using a docker image
 for this makes it easy to get going with the same build environment as used by
@@ -54,3 +65,8 @@ The image is also made so that the default user has the same UID:GID as the curr
 system user. This is so that the built files are owned by the current user on the
 host machine(otherwise they might be owned by root).
 
+## Docbuilder @ manual.mahara.org
+
+manual.mahara.org uses this project as a sub module to make use of the same doc
+builder. So any changes to how the doc builder is created need to be applied to
+that project by Catalyst staff.

build-builder.sh

+#!/bin/bash
+# Builds and/or refreshes the Mahara docbuilder image.
+
+BASE_DIR=$(dirname $0)
+
+cd ${BASE_DIR}
+docker pull debian:stable
+docker build --build-arg IMAGE_UID=`id -u` --build-arg IMAGE_GID=`id -g` --tag mahara/docbuilder .

local-server.sh

+#!/bin/bash
+#
+# Runs a dockerized nginx web server that will serve the Mahara manual
+# that has been built.
+#
+# This script will start the nginx container and publish it's port 80 to
+# ${CONTAINER_LISTEN_PORT} which will default to port 80 on the host machine.
+# If this does not suit you set an environment variable CONTAINER_LISTEN_PORT
+# with the port that you do want to use.
+
+CONTAINTER_NAME=${CONTAINTER_NAME:-mahara-nginx}
+CONTAINER_LISTEN_PORT=${CONTAINER_LISTEN_PORT:-80}
+
+cd $(dirname $0)/..
+
+if [[ "$1" == "stop" ]] ; then
+  docker container stop ${CONTAINTER_NAME}
+elif [[ "$1" == "start" ]] ; then
+  docker run --rm --name ${CONTAINTER_NAME} \
+    -p ${CONTAINER_LISTEN_PORT}:80 \
+    -v $(pwd)/build/html:/usr/share/nginx/html:ro \
+    -d nginx
+
+  echo "View the manual at http://localhost:${CONTAINER_LISTEN_PORT}/en/"
+else
+  echo "Usage $0 start|stop"
+fi

requirements.txt

-Sphinx==2.3.1
+Sphinx==3.1.2
 sphinxjp.themes.basicstrap==0.5.0

source/mahara/layout.html

@@ -107,6 +107,7 @@
             VERSION:     '{{ release|e }}',
             COLLAPSE_INDEX: false,
             FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
+            LINK_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
             HAS_SOURCE:  {{ has_source|lower }}
   };
 </script>