mirror
/
openmw
mirror of https://github.com/OpenMW/openmw.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Integrate Lua doc into sphinx doc (issue #5931)

Browse Source
dont-compose-content
Petr Mikheev 4 years ago
parent 4eb5841c60
commit 25cc884c17
18 changed files with 295 additions and 72 deletions
Show Stats Download Patch File Download Diff File

1
.gitignore vendored
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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

86
docs/source/reference/lua-scripting/api.rst
Unescape Escape 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
openmw_async
openmw_query
openmw_world
openmw_self
openmw_nearby
openmw_ui
openmw_aux_util
Engine handler is a function defined by a script, that can be called by the engine.
+------------------------------------------------------------------------------------------------+ - :ref:`Engine handlers reference`
| **Can be defined by any script** | - `Game object reference <openmw_core.html##(GameObject)>`_
+----------------------------------+-------------------------------------------------------------+ - `Cell reference <openmw_core.html##(Cell)>`_
| 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 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). |
+----------------------------------+-------------------------------------------------------------+
**API packages**
Packages reference
==================
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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape 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
Unescape Escape View File

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

14
files/lua_api/openmw/README.md
Unescape Escape 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
Unescape Escape 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
Write Preview
Loading…
Cancel
Save