mirror of https://github.com/OpenMW/openmw.git
Merge branch 'docs_in_docker' into 'master'
An easy way to build OpenMW documentation in docker See merge request OpenMW/openmw!2183post_malone
uramer
2 years ago
commit
db8238e4fc
@ -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
|
||||
@ -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
|
||||
```
|
||||
@ -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
|
||||
@ -0,0 +1,5 @@
|
||||
#!/bin/bash
|
||||
|
||||
pushd $( dirname -- "$0"; )
|
||||
docker build -t openmw_doc .
|
||||
popd
|
||||
@ -1,3 +1,5 @@
|
||||
parse_cmake
|
||||
sphinx==1.8.5
|
||||
docutils==0.17.1
|
||||
jinja2==3.0.0
|
||||
sphinx_rtd_theme
|
||||
|
||||
@ -0,0 +1 @@
|
||||
*.sh text eol=lf
|
||||
@ -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
|
||||
Loading…
Reference in New Issue