Skip to content

Commit

Permalink
Integrate Lua doc into sphinx doc (issue #5931)
Browse files Browse the repository at this point in the history
  • Loading branch information
@petrmikheev
petrmikheev committed Jul 9, 2021
1 parent 4eb5841 commit 25cc884
Show file tree
Hide file tree
Showing 18 changed files with 295 additions and 72 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ components/ui_contentselector.h
docs/mainpage.hpp
docs/Doxyfile
docs/DoxyfilePages
docs/source/reference/lua-scripting/generated_html
moc_*.cxx
*.cxx_parameters
*qrc_launcher.cxx
Expand Down
113 changes: 113 additions & 0 deletions docs/source/_static/luadoc.css
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 7 additions & 2 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
# serve to show the default.
import os
import sys
import subprocess

# 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
Expand Down Expand Up @@ -148,7 +149,11 @@ def get_openmw_version(haystack):

def setup(app):
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
# "<project> v<release> documentation".
Expand Down Expand Up @@ -176,7 +181,7 @@ def setup(app):
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# 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,
# using the given strftime format.
Expand Down
51 changes: 51 additions & 0 deletions docs/source/generate_luadoc.sh
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 34 additions & 52 deletions docs/source/reference/lua-scripting/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,54 +3,25 @@ Lua API reference
#################

.. toctree::
:caption: Table of Contents
:maxdepth: 2
:hidden:

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.

+------------------------------------------------------------------------------------------------+
| **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 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). |
+----------------------------------+-------------------------------------------------------------+
- :ref:`Engine handlers reference`
- `Game object reference <openmw_core.html##(GameObject)>`_
- `Cell reference <openmw_core.html##(Cell)>`_


Packages reference
==================
**API packages**

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>')``.
Expand All @@ -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. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`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. |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|`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_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 changes: 43 additions & 0 deletions docs/source/reference/lua-scripting/engine_handlers.rst
View file
Original file line number Diff line number Diff line change
@@ -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 change: 1 addition & 0 deletions docs/source/reference/lua-scripting/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ OpenMW Lua scripting

.. toctree::
:caption: Table of Contents
:includehidden:
:maxdepth: 2

overview
Expand Down
5 changes: 5 additions & 0 deletions docs/source/reference/lua-scripting/openmw_async.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Package openmw.async
====================

.. raw:: html
:file: generated_html/openmw_async.html
5 changes: 5 additions & 0 deletions docs/source/reference/lua-scripting/openmw_aux_util.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Package openmw_aux.util
=======================

.. raw:: html
:file: generated_html/openmw_aux_util.html
5 changes: 5 additions & 0 deletions docs/source/reference/lua-scripting/openmw_core.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Package openmw.core
===================

.. raw:: html
:file: generated_html/openmw_core.html
5 changes: 5 additions & 0 deletions docs/source/reference/lua-scripting/openmw_nearby.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Package openmw.nearby
=====================

.. raw:: html
:file: generated_html/openmw_nearby.html
5 changes: 5 additions & 0 deletions docs/source/reference/lua-scripting/openmw_query.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Package openmw.query
====================

.. raw:: html
:file: generated_html/openmw_query.html
Loading

0 comments on commit 25cc884

Please sign in to comment.