From 540a22b02351055ccaddd1fbf52b671520629cf4 Mon Sep 17 00:00:00 2001 From: Petr Mikheev Date: Tue, 9 Aug 2022 09:29:02 +0000 Subject: [PATCH] An easy way to build OpenMW documentation in docker --- docs/Dockerfile | 11 +++ docs/README.md | 73 +++++++++++++++++++ docs/build_docs.sh | 6 ++ docs/prepare_docker_image.sh | 5 ++ docs/requirements.txt | 2 + docs/source/.gitattributes | 1 + docs/source/generate_luadoc.sh | 60 +++------------ .../source/install_luadocumentor_in_docker.sh | 34 +++++++++ 8 files changed, 142 insertions(+), 50 deletions(-) create mode 100644 docs/Dockerfile create mode 100644 docs/README.md create mode 100755 docs/build_docs.sh create mode 100755 docs/prepare_docker_image.sh create mode 100644 docs/source/.gitattributes create mode 100644 docs/source/install_luadocumentor_in_docker.sh diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000000..345d6ddb93 --- /dev/null +++ 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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..f98cf56054 --- /dev/null +++ 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 +``` diff --git a/docs/build_docs.sh b/docs/build_docs.sh new file mode 100755 index 0000000000..33b3af2fc3 --- /dev/null +++ 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 diff --git a/docs/prepare_docker_image.sh b/docs/prepare_docker_image.sh new file mode 100755 index 0000000000..e77f3475f6 --- /dev/null +++ b/docs/prepare_docker_image.sh @@ -0,0 +1,5 @@ +#!/bin/bash + +pushd $( dirname -- "$0"; ) +docker build -t openmw_doc . +popd diff --git a/docs/requirements.txt b/docs/requirements.txt index ac82149f5d..9bfff7e9f2 100644 --- 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 diff --git a/docs/source/.gitattributes b/docs/source/.gitattributes new file mode 100644 index 0000000000..dfdb8b771c --- /dev/null +++ b/docs/source/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/docs/source/generate_luadoc.sh b/docs/source/generate_luadoc.sh index f71e3110cb..164074d5ca 100755 --- 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 diff --git a/docs/source/install_luadocumentor_in_docker.sh b/docs/source/install_luadocumentor_in_docker.sh new file mode 100644 index 0000000000..1853058bb7 --- /dev/null +++ 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