Files

73 lines
2.2 KiB
Markdown

# 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 Ubuntu 22.04 and installs the system tools and Python packages required to build the documentation. The bundled installation script builds Lua 5.1 and LuaRocks and installs a pinned version of openmwluadocumentor.
### 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.2.0-1.rockspec
luarocks --local install openmwluadocumentor-0.2.0-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.2.0-1.rockspec
luarocks --local install openmwluadocumentor-0.2.0-1.src.rock
```
### Generating HTML
Run the following command from OpenMW source directory to generate the documentation:
```bash
sphinx-build docs/source docs/build
```