From 25cc884c173a86196ec81f854cc9f3cb8460cd9b Mon Sep 17 00:00:00 2001 From: Petr Mikheev Date: Sun, 25 Apr 2021 00:55:08 +0200 Subject: [PATCH] Integrate Lua doc into sphinx doc (issue #5931) --- .gitignore | 1 + docs/source/_static/luadoc.css | 113 ++++++++++++++++++ docs/source/conf.py | 9 +- docs/source/generate_luadoc.sh | 51 ++++++++ docs/source/reference/lua-scripting/api.rst | 86 ++++++------- .../lua-scripting/engine_handlers.rst | 43 +++++++ docs/source/reference/lua-scripting/index.rst | 1 + .../reference/lua-scripting/openmw_async.rst | 5 + .../lua-scripting/openmw_aux_util.rst | 5 + .../reference/lua-scripting/openmw_core.rst | 5 + .../reference/lua-scripting/openmw_nearby.rst | 5 + .../reference/lua-scripting/openmw_query.rst | 5 + .../reference/lua-scripting/openmw_self.rst | 5 + .../reference/lua-scripting/openmw_ui.rst | 5 + .../reference/lua-scripting/openmw_util.rst | 5 + .../reference/lua-scripting/openmw_world.rst | 5 + files/lua_api/openmw/README.md | 14 --- files/lua_api/openmw/generate_luadoc.sh | 4 - 18 files changed, 295 insertions(+), 72 deletions(-) create mode 100644 docs/source/_static/luadoc.css create mode 100755 docs/source/generate_luadoc.sh create mode 100644 docs/source/reference/lua-scripting/engine_handlers.rst create mode 100644 docs/source/reference/lua-scripting/openmw_async.rst create mode 100644 docs/source/reference/lua-scripting/openmw_aux_util.rst create mode 100644 docs/source/reference/lua-scripting/openmw_core.rst create mode 100644 docs/source/reference/lua-scripting/openmw_nearby.rst create mode 100644 docs/source/reference/lua-scripting/openmw_query.rst create mode 100644 docs/source/reference/lua-scripting/openmw_self.rst create mode 100644 docs/source/reference/lua-scripting/openmw_ui.rst create mode 100644 docs/source/reference/lua-scripting/openmw_util.rst create mode 100644 docs/source/reference/lua-scripting/openmw_world.rst delete mode 100644 files/lua_api/openmw/README.md delete mode 100755 files/lua_api/openmw/generate_luadoc.sh diff --git a/.gitignore b/.gitignore index 1905957d9b..5c07d3e54a 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/docs/source/_static/luadoc.css b/docs/source/_static/luadoc.css new file mode 100644 index 0000000000..aa83013def --- /dev/null +++ b/docs/source/_static/luadoc.css @@ -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;} + diff --git a/docs/source/conf.py b/docs/source/conf.py index 72bb17adbb..7f2affbb75 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 @@ -148,7 +149,11 @@ html_theme = 'sphinx_rtd_theme' 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 # " v documentation". @@ -176,7 +181,7 @@ html_static_path = [ # 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. diff --git a/docs/source/generate_luadoc.sh b/docs/source/generate_luadoc.sh new file mode 100755 index 0000000000..7a238eca5a --- /dev/null +++ b/docs/source/generate_luadoc.sh @@ -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 + diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst index f98d4ef074..3a18f2445a 100644 --- a/docs/source/reference/lua-scripting/api.rst +++ b/docs/source/reference/lua-scripting/api.rst @@ -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 `_ +- `Cell reference `_ - -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('')``. @@ -63,23 +34,34 @@ Player scripts are local scripts that are attached to a player. +=========================================================+====================+===============================================================+ |:ref:`openmw.interfaces