mirror/openmw
1
0
Fork 0
mirror of https://github.com/OpenMW/openmw.git synced 2025-07-12 18:41:42 +00:00
Code Issues Releases Wiki Activity

Integrate Lua doc into sphinx doc (issue #5931)

Browse source
This commit is contained in:
Petr Mikheev 2021-04-25 00:55:08 +02:00
parent 4eb5841c60
commit 25cc884c17
18 changed files with 296 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -72,6 +72,7 @@ components/ui_contentselector.h
docs/mainpage.hpp docs/mainpage.hpp
docs/Doxyfile docs/Doxyfile
docs/DoxyfilePages docs/DoxyfilePages
docs/source/reference/lua-scripting/generated_html
moc_*.cxx moc_*.cxx
*.cxx_parameters *.cxx_parameters
*qrc_launcher.cxx *qrc_launcher.cxx

113
docs/source/_static/luadoc.css Normal file
View file

@ -0,0 +1,113 @@
#luadoc tt { font-family: monospace; }
#luadoc p,
#luadoc td,
#luadoc th { font-size: .95em; line-height: 1.2em;}
#luadoc p,
#luadoc ul
{ margin: 10px 0 0 10px;}
#luadoc strong { font-weight: bold;}
#luadoc em { font-style: italic;}
#luadoc h1 {
font-size: 1.5em;
margin: 25px 0 20px 0;
}
#luadoc h2,
#luadoc h3,
#luadoc h4 { margin: 15px 0 10px 0; }
#luadoc h2 { font-size: 1.25em; }
#luadoc h3 { font-size: 1.15em; }
#luadoc h4 { font-size: 1.06em; }
#luadoc hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
#luadoc blockquote { margin-left: 3em; }
#luadoc ul { list-style-type: disc; }
#luadoc p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
#luadoc p:first-child {
margin-top: 0px;
}
#luadoc table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
#luadoc table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
#luadoc table.function_list td.name { background-color: #f0f0f0; }
#luadoc table.function_list td.summary { width: 100%; }
#luadoc dl.table dt,
#luadoc dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
#luadoc dl.table dd,
#luadoc dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
#luadoc dl.table h3,
#luadoc dl.function h3 {font-size: .95em;}
#luadoc pre.example {
background-color: #eeffcc;
border: 1px solid #e1e4e5;
padding: 10px;
margin: 10px 0 10px 0;
overflow-x: auto;
}
#luadoc code {
background-color: inherit;
color: inherit;
border: none;
font-family: monospace;
}
#luadoc pre.example code {
color: #404040;
background-color: #eeffcc;
border: none;
white-space: pre;
padding: 0px;
}
#luadoc dt {
background: inherit;
color: inherit;
width: 100%;
padding: 0px;
}
#luadoc a:not(:link) {
font-weight: bold;
color: #000;
text-decoration: none;
cursor: inherit;
}
#luadoc a:link { font-weight: bold; color: #004080; text-decoration: none; }
#luadoc a:visited { font-weight: bold; color: #006699; text-decoration: none; }
#luadoc a:link:hover { text-decoration: underline; }
#luadoc dl,
#luadoc dd {margin: 0px; line-height: 1.2em;}
#luadoc li {list-style: bullet;}

9
docs/source/conf.py
View file

@ -13,6 +13,7 @@
# serve to show the default. # serve to show the default.
import os import os
import sys import sys
import subprocess
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
@ -148,7 +149,11 @@ html_theme = 'sphinx_rtd_theme'
def setup(app): def setup(app):
app.add_stylesheet('figures.css') app.add_stylesheet('figures.css')
app.add_stylesheet('luadoc.css')
try:
subprocess.call(project_root + '/docs/source/generate_luadoc.sh')
except Exception as e:
print('Can\'t generate Lua API documentation:', e)
# The name for this set of Sphinx documents. If None, it defaults to # The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation". # "<project> v<release> documentation".
@ -176,7 +181,7 @@ html_static_path = [
# Add any extra paths that contain custom files (such as robots.txt or # Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied # .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation. # directly to the root of the documentation.
html_extra_path = ['generated-luadoc'] #html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.

51
docs/source/generate_luadoc.sh Executable file
View file

@ -0,0 +1,51 @@
#!/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
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 install checks
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
rm -f $OUTPUT_DIR/*.html
cd $FILES_DIR/lua_api
~/.luarocks/bin/openmwluadocumentor -f doc -d $OUTPUT_DIR openmw/*lua
cd $FILES_DIR/builtin_scripts
~/.luarocks/bin/openmwluadocumentor -f doc -d $OUTPUT_DIR openmw_aux/*lua

88
docs/source/reference/lua-scripting/api.rst
View file

@ -3,54 +3,25 @@ Lua API reference
################# #################
.. toctree:: .. toctree::
:caption: Table of Contents :hidden:
:maxdepth: 2
Engine handlers reference engine_handlers
========================= openmw_util
openmw_core
Engine handler is a function defined by a script, that can be called by the engine. openmw_async
openmw_query
+------------------------------------------------------------------------------------------------+ openmw_world
| **Can be defined by any script** | openmw_self
+----------------------------------+-------------------------------------------------------------+ openmw_nearby
| onUpdate(dt) | | Called every frame if game not paused. `dt` is the time | openmw_ui
| | | from the last update in seconds. | openmw_aux_util
+----------------------------------+-------------------------------------------------------------+
| onSave() -> data | | Called when the game is saving. May be called in inactive |
| | | state, so it shouldn't use `openmw.nearby`. |
+----------------------------------+-------------------------------------------------------------+
| onLoad(data) | | Called on loading with the data previosly returned by |
| | | onSave. During loading the object is always in inactive. |
+----------------------------------+-------------------------------------------------------------+
| **Only for global scripts** |
+----------------------------------+-------------------------------------------------------------+
| onNewGame() | New game is started |
+----------------------------------+-------------------------------------------------------------+
| onPlayerAdded(player) |Player added to game world. The argument is a `Game object`. |
+----------------------------------+-------------------------------------------------------------+
| onActorActive(actor) | Actor (NPC or Creature) becomes active. |
+----------------------------------+-------------------------------------------------------------+
| **Only for local scripts** |
+----------------------------------+-------------------------------------------------------------+
| onActive() | | Called when the object becomes active (either a player |
| | | came to this cell again, or a save was loaded). |
+----------------------------------+-------------------------------------------------------------+
| onInactive() | | Object became inactive. Since it is inactive the handler |
| | | can not access anything nearby, but it is possible to send|
| | | an event to global scripts. |
+----------------------------------+-------------------------------------------------------------+
| onConsume(recordId) | | Called if `recordId` (e.g. a potion) is consumed. |
+----------------------------------+-------------------------------------------------------------+
| **Only for local scripts attached to a player** |
+----------------------------------+-------------------------------------------------------------+
| onKeyPress(symbol, modifiers) | | Key pressed. `Symbol` is an ASCII code, `modifiers` is |
| | | a binary OR of flags of special keys (ctrl, shift, alt). |
+----------------------------------+-------------------------------------------------------------+
Packages reference - :ref:`Engine handlers reference`
================== - `Game object reference <openmw_core.html##(GameObject)>`_
- `Cell reference <openmw_core.html##(Cell)>`_
**API packages**
API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction. API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction.
A package can be loaded with ``require('<package name>')``. A package can be loaded with ``require('<package name>')``.
@ -63,23 +34,34 @@ Player scripts are local scripts that are attached to a player.
+=========================================================+====================+===============================================================+ +=========================================================+====================+===============================================================+
|:ref:`openmw.interfaces <Script interfaces>` | everywhere | | Public interfaces of other scripts. | |:ref:`openmw.interfaces <Script interfaces>` | everywhere | | Public interfaces of other scripts. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.util <../../lua-api-reference/util.html>`_ | everywhere | | Defines utility functions and classes like 3D vectors, | |:ref:`openmw.util <Package openmw.util>` | everywhere | | Defines utility functions and classes like 3D vectors, |
| | | | that don't depend on the game world. | | | | | that don't depend on the game world. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.core <../../lua-api-reference/core.html>`_ | everywhere | | Functions that are common for both global and local scripts | |:ref:`openmw.core <Package openmw.core>` | everywhere | | Functions that are common for both global and local scripts |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.async <../../lua-api-reference/async.html>`_ | everywhere | | Timers (implemented) and coroutine utils (not implemented) | |:ref:`openmw.async <Package openmw.async>` | everywhere | | Timers (implemented) and coroutine utils (not implemented) |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.query <../../lua-api-reference/query.html>`_ | everywhere | | Tools for constructing queries: base queries and fields. | |:ref:`openmw.query <Package openmw.query>` | everywhere | | Tools for constructing queries: base queries and fields. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.world <../../lua-api-reference/world.html>`_ | by global scripts | | Read-write access to the game world. | |:ref:`openmw.world <Package openmw.world>` | by global scripts | | Read-write access to the game world. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.self <../../lua-api-reference/self.html>`_ | by local scripts | | Full access to the object the script is attached to. | |:ref:`openmw.self <Package openmw.self>` | by local scripts | | Full access to the object the script is attached to. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.nearby <../../lua-api-reference/nearby.html>`_ | by local scripts | | Read-only access to the nearest area of the game world. | |:ref:`openmw.nearby <Package openmw.nearby>` | by local scripts | | Read-only access to the nearest area of the game world. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`openmw.ui <../../lua-api-reference/ui.html>`_ | by player scripts | | Controls user interface | |:ref:`openmw.ui <Package openmw.ui>` | by player scripts | | Controls user interface |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|openmw.camera | by player scripts | | Controls camera (not implemented) | |openmw.camera | by player scripts | | Controls camera (not implemented) |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
**openmw_aux**
``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
| Built-in library | Can be used | Description |
+=========================================================+====================+===============================================================+
|:ref:`openmw_aux.util <Package openmw_aux.util>` | everywhere | | Miscellaneous utils |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+

43
docs/source/reference/lua-scripting/engine_handlers.rst Normal file
View file

@ -0,0 +1,43 @@
Engine handlers reference
=========================
Engine handler is a function defined by a script, that can be called by the engine.
+---------------------------------------------------------------------------------------------------------+
| **Can be defined by any script** |
+----------------------------------+----------------------------------------------------------------------+
| onUpdate(dt) | | Called every frame if game not paused. `dt` is the time |
| | | from the last update in seconds. |
+----------------------------------+----------------------------------------------------------------------+
| onSave() -> data | | Called when the game is saving. May be called in inactive |
| | | state, so it shouldn't use `openmw.nearby`. |
+----------------------------------+----------------------------------------------------------------------+
| onLoad(data) | | Called on loading with the data previosly returned by |
| | | onSave. During loading the object is always inactive. |
+----------------------------------+----------------------------------------------------------------------+
| **Only for global scripts** |
+----------------------------------+----------------------------------------------------------------------+
| onNewGame() | New game is started |
+----------------------------------+----------------------------------------------------------------------+
| onPlayerAdded(player) | Player added to the game world. The argument is a `Game object`. |
+----------------------------------+----------------------------------------------------------------------+
| onActorActive(actor) | Actor (NPC or Creature) becomes active. |
+----------------------------------+----------------------------------------------------------------------+
| **Only for local scripts** |
+----------------------------------+----------------------------------------------------------------------+
| onActive() | | Called when the object becomes active (either a player |
| | | came to this cell again, or a save was loaded). |
+----------------------------------+----------------------------------------------------------------------+
| onInactive() | | Object became inactive. Since it is inactive the handler |
| | | can not access anything nearby, but it is possible to send |
| | | an event to global scripts. |
+----------------------------------+----------------------------------------------------------------------+
| onConsume(recordId) | | Called if `recordId` (e.g. a potion) is consumed. |
+----------------------------------+----------------------------------------------------------------------+
| **Only for local scripts attached to a player** |
+----------------------------------+----------------------------------------------------------------------+
| onKeyPress(key) | | `Key <openmw_core.html##(KeyboardEvent)>`_ pressed. Usage example: |
| | | ``if key.symbol == 'z' and key.withShift then ...`` |
+----------------------------------+----------------------------------------------------------------------+

1
docs/source/reference/lua-scripting/index.rst
View file

@ -7,6 +7,7 @@ OpenMW Lua scripting
.. toctree:: .. toctree::
:caption: Table of Contents :caption: Table of Contents
:includehidden:
:maxdepth: 2 :maxdepth: 2
overview overview

5
docs/source/reference/lua-scripting/openmw_async.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.async
====================
.. raw:: html
:file: generated_html/openmw_async.html

5
docs/source/reference/lua-scripting/openmw_aux_util.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw_aux.util
=======================
.. raw:: html
:file: generated_html/openmw_aux_util.html

5
docs/source/reference/lua-scripting/openmw_core.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.core
===================
.. raw:: html
:file: generated_html/openmw_core.html

5
docs/source/reference/lua-scripting/openmw_nearby.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.nearby
=====================
.. raw:: html
:file: generated_html/openmw_nearby.html

5
docs/source/reference/lua-scripting/openmw_query.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.query
====================
.. raw:: html
:file: generated_html/openmw_query.html

5
docs/source/reference/lua-scripting/openmw_self.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.self
===================
.. raw:: html
:file: generated_html/openmw_self.html

5
docs/source/reference/lua-scripting/openmw_ui.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.ui
=================
.. raw:: html
:file: generated_html/openmw_ui.html

5
docs/source/reference/lua-scripting/openmw_util.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.util
===================
.. raw:: html
:file: generated_html/openmw_util.html

5
docs/source/reference/lua-scripting/openmw_world.rst Normal file
View file

@ -0,0 +1,5 @@
Package openmw.world
====================
.. raw:: html
:file: generated_html/openmw_world.html

14
files/lua_api/openmw/README.md
View file

@ -1,14 +0,0 @@
`*.lua` files from this dir are also used to generate html documentation.
After every change run the following commands to update it:
```
luadocumentor -f doc -d ../../../docs/source/generated-luadoc/lua-api-reference *.lua
sed -i 's/openmw\.\(\w*\)\(\#\|\.html\)/\1\2/g' ../../../docs/source/generated-luadoc/lua-api-reference/*.html
```
`luadocumentor` can be installed via `luarocks`:
```
luarocks install luadocumentor
```

4
files/lua_api/openmw/generate_luadoc.sh
View file

@ -1,4 +0,0 @@
#!/bin/bash
luadocumentor -f doc -d ../../../docs/source/generated-luadoc/lua-api-reference *.lua
sed -i 's/openmw\.\(\w*\)\(\#\|\.html\)/\1\2/g' ../../../docs/source/generated-luadoc/lua-api-reference/*.html