mirror of https://github.com/OpenMW/openmw.git
An easy way to build OpenMW documentation in docker
parent
17fcc254c0
commit
540a22b023
@ -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
|
parse_cmake
|
||||||
sphinx==1.8.5
|
sphinx==1.8.5
|
||||||
docutils==0.17.1
|
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