From fcca617eaf6389e76d51c636329b3ed131deccd0 Mon Sep 17 00:00:00 2001 From: Tom Hiller Date: Sat, 18 Aug 2018 19:39:55 -0400 Subject: util/docker/doc.coreboot.org/Dockerfile: Use alpine:3.8, Sphinx 1.7 With Alpine base, use pip to install Sphinx 1.7 and Sphinx-autobuild Alpine, a 4.5MB base, is used over Debian Stable, 101MB, to cut down the total size of the docker image. Change-Id: I53f246206458b1de34cd7f3a42481b91ca285ff0 Signed-off-by: Tom Hiller Reviewed-on: https://review.coreboot.org/28211 Tested-by: build bot (Jenkins) Reviewed-by: Patrick Georgi --- util/docker/doc.coreboot.org/Dockerfile | 25 ++++++++++++++++++---- util/docker/doc.coreboot.org/README.md | 33 ++++++++++++++++++++++++++++-- util/docker/doc.coreboot.org/makeSphinx.sh | 12 +++++++++++ 3 files changed, 64 insertions(+), 6 deletions(-) create mode 100755 util/docker/doc.coreboot.org/makeSphinx.sh (limited to 'util') diff --git a/util/docker/doc.coreboot.org/Dockerfile b/util/docker/doc.coreboot.org/Dockerfile index 72b699fbdd..8de0d46f65 100644 --- a/util/docker/doc.coreboot.org/Dockerfile +++ b/util/docker/doc.coreboot.org/Dockerfile @@ -1,5 +1,22 @@ -FROM debian:stable -RUN apt-get update && apt-get install -y make python-sphinx python-recommonmark python-sphinx-rtd-theme git && apt-get clean -USER nobody +FROM alpine:3.8 + +COPY makeSphinx.sh /makeSphinx.sh + +RUN apk add --no-cache python3 make bash git \ + && pip3 install --upgrade --no-cache-dir pip \ + && pip3 install --no-cache-dir \ + sphinx===1.7.7 \ + sphinx_rtd_theme===0.4.1 \ + recommonmark===0.4.0 \ + sphinx_autobuild===0.7.1 \ + && chmod 755 /makeSphinx.sh + VOLUME /data-in /data-out -ENTRYPOINT bash -c "cd /data-in/Documentation && make sphinx BUILDDIR=/tmp/build && rm -rf /data-out/* && mv /tmp/build/html/* /data-out/" + +# For Sphinx-autobuild +# Port 8000 - HTTP server +# Port 35729 - websockets connection to allow automatic browser reloads after each build +EXPOSE 8000 35729 + +ENTRYPOINT ["/bin/bash", "/makeSphinx.sh"] +CMD [] diff --git a/util/docker/doc.coreboot.org/README.md b/util/docker/doc.coreboot.org/README.md index 11c095d18e..d5d483eeba 100644 --- a/util/docker/doc.coreboot.org/README.md +++ b/util/docker/doc.coreboot.org/README.md @@ -1,3 +1,32 @@ -How to use: +# doc.coreboot.org + Docker container for generating and developing documentation for doc.coreboot.org -docker run --rm -v $path-to-coreboot.git:/data-in:ro -v $path-to-html-output:/data-out $image +**NOTE**: All paths are from the base of the coreboot git repo. + +### Build + +```sh + docker build --force-rm -t "doc.coreboot.org" "$PWD/util/docker/doc.coreboot.org/" +``` + +### Generating production HTML + +```sh +# To ensure the output directory is given the correct permissions, make sure to +# created it before running docker the first time. +mkdir -p "$PWD/Documentation/_build/" + +docker run -it --rm \ + --user "$(id -u):$(id -g)" \ + -v "$PWD/:/data-in/:ro" \ + -v "$PWD/Documentation/_build/:/data-out/" \ + doc.coreboot.org +``` + +### live reloaded with web server +On the host machine, open a browser to the address http://0.0.0.0:8000 +```sh +docker run -it --rm \ + --net=host -v "$PWD/:/data-in/:ro" \ + doc.coreboot.org livehtml +``` diff --git a/util/docker/doc.coreboot.org/makeSphinx.sh b/util/docker/doc.coreboot.org/makeSphinx.sh new file mode 100755 index 0000000000..3b0c4e336f --- /dev/null +++ b/util/docker/doc.coreboot.org/makeSphinx.sh @@ -0,0 +1,12 @@ +#!/bin/bash + +if [ "$1" == "livehtml" ]; then + echo "Starting live documentation build" + cd /data-in/Documentation && make livesphinx BUILDDIR=/tmp/build +else + echo "Starting production documentation build" + cd /data-in/Documentation \ + && make sphinx BUILDDIR=/tmp/build \ + && rm -rf /data-out/* \ + && mv /tmp/build/html/* /data-out/ +fi -- cgit v1.2.3