An easy way to build OpenMW documentation in docker

2025-01-29 22:45:36 +00:00 · 2022-08-09 09:29:02 +00:00 · 2022-08-09 09:29:02 +00:00 · 540a22b023
commit 540a22b023
parent 17fcc254c0
8 changed files with 142 additions and 50 deletions
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@ -0,0 +1,11 @@
+FROM readthedocs/build:latest
+ENV HOME="/home/docs"
+RUN touch /home/docs/omw_luadoc_docker
+
+COPY requirements.txt ./
+RUN pip3 install -r requirements.txt
+
+COPY source/install_luadocumentor_in_docker.sh ./
+RUN bash ./install_luadocumentor_in_docker.sh
+
+VOLUME /openmw
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,73 @@
+# Building OpenMW documentation
+
+## Building in Docker (the recommended way)
+
+### Preparing Docker image
+
+Run the following commands from OpenMW source directory to build a new Docker image `openmw_doc`:
+```bash
+cd docs
+docker build -t openmw_doc .
+cd ..
+```
+
+(or run script `docs/prepare_docker_image.sh`)
+
+This step needs to be repeated only if any dependencies were changed.
+
+The image is based on `readthedocs/build:latest` that is newer than the image readthedocs uses by default (`readthedocs/build:stable`).
+So if after some readthedocs update the documentation will stop building, there is a chance to detect it before the online docs will break.
+
+### Generating HTML
+
+Run the following command from OpenMW source directory to generate the documentation:
+```bash
+docker run --user "$(id -u)":"$(id -g)" --volume "$PWD":/openmw openmw_doc \
+    sphinx-build /openmw/docs/source /openmw/docs/build
+```
+
+(or run script `docs/build_docs.sh`)
+
+To view the generated documentation just open `docs/build/index.html` in a browser.
+
+## Building without Docker (an alternative way)
+
+Building documentation without Docker is more complicated as it requires multiple dependencies.
+
+### Installation of required python packages
+
+From OpenMW source directory
+```bash
+pip3 install -r docs/requirements.txt
+```
+
+### Installation of openmwluadocumentor:
+
+**Debian/Ubuntu**
+
+```bash
+sudo apt install luarocks
+git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
+cd openmw-luadocumentor/luarocks
+luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
+luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
+```
+
+**Windows**
+
+- install LuaRocks (heavily recommended to use the standalone package)
+  https://github.com/luarocks/luarocks/wiki/Installation-instructions-for-Windows
+- `git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git`
+- `cd openmw-luadocumentor/luarocks`
+- open "Developer Command Prompt for VS <2017/2019>" in this directory and run:
+```bash
+luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
+luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
+```
+
+### Generating HTML
+
+Run the following command from OpenMW source directory to generate the documentation:
+```bash
+sphinx-build docs/source docs/build
+```
--- a/docs/build_docs.sh
+++ b/docs/build_docs.sh
@ -0,0 +1,6 @@
+#!/bin/bash
+
+pushd $( dirname -- "$0"; )
+docker run --user "$(id -u)":"$(id -g)" --volume "$PWD/..":/openmw openmw_doc \
+    sphinx-build /openmw/docs/source /openmw/docs/build
+popd
--- a/docs/prepare_docker_image.sh
+++ b/docs/prepare_docker_image.sh
@ -0,0 +1,5 @@
+#!/bin/bash
+
+pushd $( dirname -- "$0"; )
+docker build -t openmw_doc .
+popd
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@ -1,3 +1,5 @@
 parse_cmake
 sphinx==1.8.5
 docutils==0.17.1
+jinja2==3.0.0
+sphinx_rtd_theme
--- a/docs/source/.gitattributes
+++ b/docs/source/.gitattributes
@ -0,0 +1 @@
+*.sh text eol=lf
--- a/docs/source/generate_luadoc.sh
+++ b/docs/source/generate_luadoc.sh
@ -1,61 +1,21 @@
 #!/bin/bash

-# How to install openmwluadocumentor:
-
-# sudo apt install luarocks
-# git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
-# cd openmw-luadocumentor/luarocks
-# luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
-# luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
-
-# How to install on Windows:
-
-# install LuaRocks (heavily recommended to use the standalone package)
-#   https://github.com/luarocks/luarocks/wiki/Installation-instructions-for-Windows
-# git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
-# cd openmw-luadocumentor/luarocks
-# open "Developer Command Prompt for VS <2017/2019>" in this directory and run:
-#   luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
-#   luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
-# open "Git Bash" in the same directory and run script:
-#   ./generate_luadoc.sh
-
-if [ -f /.dockerenv ]; then
-    # We are inside readthedocs pipeline
-    echo "Install lua 5.1"
-    cd ~
-    curl -R -O https://www.lua.org/ftp/lua-5.1.5.tar.gz
-    tar -zxf lua-5.1.5.tar.gz
-    cd lua-5.1.5/
-    make linux
-    PATH=$PATH:~/lua-5.1.5/src
-
-    echo "Install luarocks"
-    cd ~
-    wget https://luarocks.org/releases/luarocks-2.4.2.tar.gz
-    tar zxpf luarocks-2.4.2.tar.gz
-    cd luarocks-2.4.2/
-    ./configure --with-lua-bin=$HOME/lua-5.1.5/src --with-lua-include=$HOME/lua-5.1.5/src --prefix=$HOME/luarocks
-    make build
-    make install
-    PATH=$PATH:~/luarocks/bin
-
-    echo "Install openmwluadocumentor"
-    cd ~
-    git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
-    cd openmw-luadocumentor/luarocks
-    luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
-    luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
-fi
-
 DOCS_SOURCE_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 FILES_DIR=$DOCS_SOURCE_DIR/../../files
 OUTPUT_DIR=$DOCS_SOURCE_DIR/reference/lua-scripting/generated_html
 DOCUMENTOR_PATH=~/.luarocks/bin/openmwluadocumentor

 if [ ! -x $DOCUMENTOR_PATH ]; then
-  # running on Windows?
-  DOCUMENTOR_PATH="$APPDATA/LuaRocks/bin/openmwluadocumentor.bat"
+    if [ -f /.dockerenv ] || [ -f /home/docs/omw_luadoc_docker ]; then
+        . install_luadocumentor_in_docker.sh
+    else
+        # running on Windows?
+        DOCUMENTOR_PATH="$APPDATA/LuaRocks/bin/openmwluadocumentor.bat"
+    fi
+fi
+if [ ! -x $DOCUMENTOR_PATH ]; then
+    echo "openmwluadocumentor not found; See README.md for installation instructions."
+    exit
 fi

 rm -f $OUTPUT_DIR/*.html
--- a/docs/source/install_luadocumentor_in_docker.sh
+++ b/docs/source/install_luadocumentor_in_docker.sh
@ -0,0 +1,34 @@
+if [ ! -f /.dockerenv ] && [ ! -f /home/docs/omw_luadoc_docker ]; then
+    echo 'This script installs lua-5.1, luarocks, and openmwluadocumentor to $HOME. Should be used only in docker.'
+    exit 1
+fi
+
+echo "Install lua 5.1"
+cd ~
+curl -R -O https://www.lua.org/ftp/lua-5.1.5.tar.gz
+tar -zxf lua-5.1.5.tar.gz
+rm lua-5.1.5.tar.gz
+cd lua-5.1.5/
+make linux
+cd ~
+PATH=$PATH:~/lua-5.1.5/src
+
+echo "Install luarocks"
+wget https://luarocks.org/releases/luarocks-2.4.2.tar.gz
+tar zxpf luarocks-2.4.2.tar.gz
+rm luarocks-2.4.2.tar.gz
+cd luarocks-2.4.2/
+./configure --with-lua-bin=$HOME/lua-5.1.5/src --with-lua-include=$HOME/lua-5.1.5/src --prefix=$HOME/luarocks
+make build
+make install
+cd ~
+rm -r luarocks-2.4.2
+PATH=$PATH:~/luarocks/bin
+
+echo "Install openmwluadocumentor"
+git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
+cd openmw-luadocumentor/luarocks
+luarocks --local pack openmwluadocumentor-0.1.1-1.rockspec
+luarocks --local install openmwluadocumentor-0.1.1-1.src.rock
+cd ~
+rm -r openmw-luadocumentor