docs - begin restructing docs

apps/openmw/mwlua/README.md

@@ -3,7 +3,7 @@
 This folder contains the C++ implementation of the Lua scripting system.
 
 For user-facing documentation, see
-[OpenMW Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html).
+[Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html).
 The documentation is generated from
 [/docs/source/reference/lua-scripting](/docs/source/reference/lua-scripting).
 You can find instructions for generating the documentation at the

docs/requirements.txt

@@ -3,3 +3,6 @@ sphinx==7.1.2
 docutils==0.18.1
 jinja2==3.1.6
 sphinx_rtd_theme==3.0.1
+sphinx-design==0.6.1
+furo==2024.8.6
+sphinx-copybutton==0.5.2

docs/source/_static/luadoc.css

@@ -1,10 +1,9 @@
 #luadoc tt { font-family: monospace; }
 
-#luadoc p,
+/* #luadoc p,
 #luadoc td,
 #luadoc th { font-size: .95em; line-height: 1.2em;}
 
-#luadoc p,
 #luadoc ul
 { margin: 10px 0 0 10px;}
 
@@ -109,5 +108,60 @@
 
 #luadoc dl,
 #luadoc dd {margin: 0px; line-height: 1.2em;}
-#luadoc li {list-style: bullet;}
+#luadoc li {list-style: bullet;} */
 
+#luadoc pre.example {
+    background-color: #eeffcc;
+    border: 1px solid #e1e4e5;
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    overflow-x: auto;
+}
+
+
+#luadoc pre.example code {
+    color: var(--color-content-foreground);
+    background-color: #eeffcc;
+    border: none;
+    white-space: pre;
+    padding: 0px;
+}
+
+#luadoc code {
+    /* background-color: inherit;
+    color: inherit;
+    border: none; */
+    font-family: monospace;
+}
+
+body[data-theme="dark"] #luadoc pre.example {
+    background-color: #eeffcc;
+}
+
+@media (prefers-color-scheme: dark) {
+    body:not([data-theme="light"]) #luadoc pre.example {
+        background-color: #eeffcc;
+    }
+}
+
+#luadoc a:not(:link) {
+    font-weight: bold;
+    color: var(--color-content-foreground);
+    text-decoration: none;
+    cursor: inherit;
+}
+
+#luadoc p em { font-family: 'monospace';}
+
+#luadoc a:link { font-weight: bold; color: var(--color-link);; text-decoration: none; }
+#luadoc a:visited { font-weight: bold; color: var(--color-link--hover); text-decoration: none; }
+#luadoc a:link:hover { text-decoration: underline; }
+
+.context-wrapper {
+    display: flex;
+    gap: 4px;
+}
+
+table.docutils {
+    width: 100%;
+}

docs/source/_static/theme.css

@@ -0,0 +1,11 @@
+.content {
+    width: 60em;
+}
+
+a.next-page, a.prev-page {
+    color: var(--color-link);
+}
+
+a.next-page:hover, a.prev-page:hover {
+    text-decoration: underline;
+}

docs/source/conf.py

@@ -37,6 +37,8 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosectionlabel',
+    'sphinx_design',
+    'sphinx_copybutton',
 ]
 
 #autosectionlabel_prefix_document = True
@@ -91,7 +93,14 @@ except Exception as ex:
 
 rst_prolog = f"""
 .. |luaApiRevision| replace:: {luaApiRevision}
+.. |luaApiRevisionBadge| replace:: :bdg-link-info-line:`API v{luaApiRevision} <openmw_core.html##(core).API_REVISION>`
+
 .. |ppApiRevision| replace:: {ppApiRevision}
+.. |bdg-ctx-menu| replace:: :bdg-warning:`menu`
+.. |bdg-ctx-global| replace:: :bdg-danger:`global`
+.. |bdg-ctx-player| replace:: :bdg-secondary:`local:player`
+.. |bdg-ctx-local| replace:: :bdg-info:`local`
+.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local`
 """
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -138,7 +147,7 @@ primary_domain = 'c'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -146,14 +155,20 @@ html_theme = 'sphinx_rtd_theme'
 html_theme_options = {
     'navigation_with_keys': True,
     'flyout_display': 'attached',
+    'sidebar_hide_name': False,
+    'top_of_page_buttons': [],
 }
 
+html_css_files = [
+    "theme.css",
+    "luadoc.css",
+    "figures.css"
+]
+
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 
 def setup(app):
-    app.add_css_file('figures.css')
-    app.add_css_file('luadoc.css')
     try:
         subprocess.call(['bash', project_root + '/docs/source/generate_luadoc.sh'])
     except Exception as e:
@@ -161,19 +176,19 @@ def setup(app):
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = 'OpenMW'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = 'OpenMW Documentation'
+# html_short_title = 'OpenMW Documentation'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png'
+html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png'
+html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/source/reference/lua-scripting/ai/combat.rst

@@ -0,0 +1,36 @@
+Combat
+======
+
+.. include:: ../version.rst
+
+Attack another actor.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - cancelOther
+    - boolean [default=true]
+    - whether to cancel all other AI packages
+  * - target
+    - `GameObject <../openmw_core.html##(GameObject)>`_ [required]
+    - the actor to attack
+
+**Examples**
+
+.. code-block:: Lua
+
+    -- from local script add package to self
+    local AI = require('openmw.interfaces').AI
+    AI.startPackage({type='Combat', target=anotherActor})
+
+    -- via event to any actor
+    actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor})

docs/source/reference/lua-scripting/ai/escort.rst

@@ -0,0 +1,49 @@
+Escort
+======
+
+.. include:: ../version.rst
+
+Escort another actor to the given location.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - cancelOther
+    - boolean [default=true]
+    - whether to cancel all other AI packages
+  * - target
+    - `GameObject <../openmw_core.html##(GameObject)>`_ [required]
+    - the actor to follow
+  * - destPosition
+    - `3d vector <../openmw_util.html##(Vector3)>`_ [required]
+    - the destination point
+  * - destCell
+    - Cell [optional]
+    - the destination cell
+  * - duration
+    - number [optional]
+    - duration in game time (will be rounded up to the next hour)
+  * - isRepeat
+    - boolean [optional]
+    - Will the package repeat (true or false)
+
+**Example**
+
+.. code-block:: Lua
+
+    actor:sendEvent('StartAIPackage', {
+        type = 'Escort',
+        target = object.self,
+        destPosition = util.vector3(x, y, z),
+        duration = 3 * time.hour,
+        isRepeat = true
+    })

docs/source/reference/lua-scripting/ai/follow.rst

@@ -0,0 +1,37 @@
+Follow
+======
+
+.. include:: ../version.rst
+
+Follow another actor.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - cancelOther
+    - boolean [default=true]
+    - whether to cancel all other AI packages
+  * - target
+    - `GameObject <../openmw_core.html##(GameObject)>`_ [required]
+    - the actor to follow
+  * - destCell
+    - Cell [optional]
+    - the destination cell
+  * - duration
+    - number [optional]
+    - duration in game time (will be rounded up to the next hour)
+  * - destPosition
+    - `3d vector <../openmw_util.html##(Vector3)>`_ [optional]
+    - the destination point
+  * - isRepeat
+    - boolean [optional]
+    - Will the package repeat (true or false)

docs/source/reference/lua-scripting/ai/pursue.rst

@@ -0,0 +1,25 @@
+Pursue
+======
+
+.. include:: ../version.rst
+
+Pursue another actor.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - cancelOther
+    - boolean [default=true]
+    - whether to cancel all other AI packages
+  * - target
+    - `GameObject <../openmw_core.html##(GameObject)>`_ [required]
+    - the actor to pursue

docs/source/reference/lua-scripting/ai/travel.rst

@@ -0,0 +1,28 @@
+Travel
+======
+
+.. include:: ../version.rst
+
+Go to given location.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - cancelOther
+    - boolean [default=true]
+    - whether to cancel all other AI packages
+  * - destPosition
+    - `3d vector <../openmw_util.html##(Vector3)>`_ [required]
+    - the point to travel to
+  * - isRepeat
+    - boolean [optional]
+    - Will the package repeat (true or false)

docs/source/reference/lua-scripting/ai/wander.rst

@@ -0,0 +1,53 @@
+Wander
+======
+
+.. include:: ../version.rst
+
+Wander nearby current position.
+
+**Arguments**
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type
+    - description
+  * - type
+    - string [required]
+    - the name of the package (see packages listed below)
+  * - distance
+    - float [default=0]
+    - the actor to follow
+  * - duration
+    - number [optional]
+    - duration in game time (will be rounded up to the next hour)
+  * - idle
+    - table [optional]
+    - Idle chance values, up to 8
+  * - isRepeat
+    - boolean [optional]
+    - Will the package repeat (true or false)
+
+**Example**
+
+.. code-block:: Lua
+
+    local idleTable = {
+        idle2 = 60,
+        idle3 = 50,
+        idle4 = 40,
+        idle5 = 30,
+        idle6 = 20,
+        idle7 = 10,
+        idle8 = 0,
+        idle9 = 25
+    }
+    actor:sendEvent('StartAIPackage', {
+        type = 'Wander',
+        distance = 5000,
+        duration = 5 * time.hour,
+        idle = idleTable,
+        isRepeat = true
+    })

docs/source/reference/lua-scripting/aipackages.rst

@@ -1,225 +0,0 @@
-Built-in AI packages
-====================
-
-.. include:: version.rst
-
-Starting an AI package
-----------------------
-
-There are two ways to start AI package:
-
-.. code-block:: Lua
-
-    -- from local script add package to self
-    local AI = require('openmw.interfaces').AI
-    AI.startPackage(options)
-
-    -- via event to any actor
-    actor:sendEvent('StartAIPackage', options)
-
-``options`` is Lua table with arguments of the AI package.
-
-**Common arguments that can be used with any AI package**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - type
-    - string [required]
-    - the name of the package (see packages listed below)
-  * - cancelOther
-    - boolean [default=true]
-    - whether to cancel all other AI packages
-
-Combat
-------
-
-Attack another actor.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - target
-    - `GameObject <openmw_core.html##(GameObject)>`_ [required]
-    - the actor to attack
-
-**Examples**
-
-.. code-block:: Lua
-
-    -- from local script add package to self
-    local AI = require('openmw.interfaces').AI
-    AI.startPackage({type='Combat', target=anotherActor})
-
-    -- via event to any actor
-    actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor})
-
-Pursue
-------
-
-Pursue another actor.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - target
-    - `GameObject <openmw_core.html##(GameObject)>`_ [required]
-    - the actor to pursue
-
-Follow
-------
-
-Follow another actor.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - target
-    - `GameObject <openmw_core.html##(GameObject)>`_ [required]
-    - the actor to follow
-  * - destCell
-    - Cell [optional]
-    - the destination cell
-  * - duration
-    - number [optional]
-    - duration in game time (will be rounded up to the next hour)
-  * - destPosition
-    - `3d vector <openmw_util.html##(Vector3)>`_ [optional]
-    - the destination point
-  * - isRepeat
-    - boolean [optional]
-    - Will the package repeat (true or false)
-
-Escort
-------
-
-Escort another actor to the given location.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - target
-    - `GameObject <openmw_core.html##(GameObject)>`_ [required]
-    - the actor to follow
-  * - destPosition
-    - `3d vector <openmw_util.html##(Vector3)>`_ [required]
-    - the destination point
-  * - destCell
-    - Cell [optional]
-    - the destination cell
-  * - duration
-    - number [optional]
-    - duration in game time (will be rounded up to the next hour)
-  * - isRepeat
-    - boolean [optional]
-    - Will the package repeat (true or false)
-
-**Example**
-
-.. code-block:: Lua
-
-    actor:sendEvent('StartAIPackage', {
-        type = 'Escort',
-        target = object.self,
-        destPosition = util.vector3(x, y, z),
-        duration = 3 * time.hour,
-        isRepeat = true
-    })
-
-Wander
-------
-
-Wander nearby current position.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - distance
-    - float [default=0]
-    - the actor to follow
-  * - duration
-    - number [optional]
-    - duration in game time (will be rounded up to the next hour)
-  * - idle
-    - table [optional]
-    - Idle chance values, up to 8
-  * - isRepeat
-    - boolean [optional]
-    - Will the package repeat (true or false)
-
-**Example**
-
-.. code-block:: Lua
-
-    local idleTable = {
-        idle2 = 60,
-        idle3 = 50,
-        idle4 = 40,
-        idle5 = 30,
-        idle6 = 20,
-        idle7 = 10,
-        idle8 = 0,
-        idle9 = 25
-    }
-    actor:sendEvent('StartAIPackage', {
-        type = 'Wander',
-        distance = 5000,
-        duration = 5 * time.hour,
-        idle = idleTable,
-        isRepeat = true
-    })
-
-Travel
-------
-
-Go to given location.
-
-**Arguments**
-
-.. list-table::
-  :header-rows: 1
-  :widths: 20 20 60
-
-  * - name
-    - type
-    - description
-  * - destPosition
-    - `3d vector <openmw_util.html##(Vector3)>`_ [required]
-    - the point to travel to
-  * - isRepeat
-    - boolean [optional]
-    - Will the package repeat (true or false)

docs/source/reference/lua-scripting/api.rst

@@ -7,54 +7,15 @@ Lua API reference
 .. toctree::
     :hidden:
 
-    engine_handlers
+    index_packages
-    user_interface
+    index_auxpackages
-    aipackages
+    index_aipackages
+    index_interfaces
+    UI <user_interface>
     setting_renderers
+    Engine Handlers <engine_handlers>
     events
-    openmw_ambient
+    Iterables <iterables>
-    openmw_animation
-    openmw_async
-    openmw_camera
-    openmw_core
-    openmw_debug
-    openmw_input
-    openmw_markup
-    openmw_menu
-    openmw_nearby
-    openmw_postprocessing
-    openmw_self
-    openmw_storage
-    openmw_types
-    openmw_ui
-    openmw_util
-    openmw_vfs
-    openmw_world
-    openmw_aux_calendar
-    openmw_aux_time
-    openmw_aux_ui
-    openmw_aux_util
-    interface_activation
-    interface_ai
-    interface_animation
-    interface_camera
-    interface_controls
-    interface_gamepadcontrols
-    interface_item_usage
-    interface_mwui
-    interface_settings
-    interface_skill_progression
-    interface_ui
-    interface_crimes
-    iterables
-
-
-- :ref:`Engine handlers reference`
-- :ref:`User interface reference <User interface reference>`
-- `Game object reference <openmw_core.html##(GameObject)>`_
-- `Cell reference <openmw_core.html##(Cell)>`_
-- :ref:`Built-in AI packages`
-- :ref:`Built-in events`
 
 **API packages**
 
@@ -66,7 +27,7 @@ Player scripts are local scripts that are attached to a player.
 
 .. include:: tables/packages.rst
 
-**openmw_aux**
+**Auxiliary packages**
 
 ``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.

docs/source/reference/lua-scripting/engine_handlers.rst

@@ -7,6 +7,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Can be defined by any script**
 
+|bdg-ctx-all|
+
 .. list-table::
   :widths: 20 80
 
@@ -16,6 +18,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Can be defined by any non-menu script**
 
+|bdg-ctx-global| |bdg-ctx-local|
+
 .. list-table::
   :widths: 20 80
 
@@ -39,6 +43,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Only for global scripts**
 
+|bdg-ctx-global|
+
 .. list-table::
   :widths: 20 80
 
@@ -61,6 +67,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Only for local scripts**
 
+|bdg-ctx-local|
+
 .. list-table::
   :widths: 20 80
 
@@ -86,6 +94,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Only menu scripts and local scripts attached to a player**
 
+|bdg-ctx-menu| |bdg-ctx-player|
+
 .. list-table::
   :widths: 20 80
 
@@ -140,6 +150,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Only for local scripts attached to a player**
 
+|bdg-ctx-player|
+
 .. list-table::
   :widths: 20 80
 
@@ -152,6 +164,8 @@ Engine handler is a function defined by a script, that can be called by the engi
 
 **Only for menu scripts**
 
+|bdg-ctx-menu|
+
 .. list-table::
   :widths: 20 80
 

docs/source/reference/lua-scripting/events.rst

@@ -1,5 +1,5 @@
-Built-in events
+Events
-===============
+======
 
 .. include:: version.rst
 

docs/source/reference/lua-scripting/index.rst

@@ -1,6 +1,6 @@
-####################
+#############
-OpenMW Lua scripting
+Lua scripting
-####################
+#############
 
 .. note::
     OpenMW Lua is not compatible with MWSE.

docs/source/reference/lua-scripting/index_aipackages.rst

@@ -0,0 +1,24 @@
+AI packages
+============
+
+.. include:: version.rst
+
+.. toctree::
+    :hidden:
+    :glob:
+
+    ai/*
+
+Starting an AI package
+----------------------
+
+There are two ways to start AI package:
+
+.. code-block:: Lua
+
+    -- from local script add package to self
+    local AI = require('openmw.interfaces').AI
+    AI.startPackage(options)
+
+    -- via event to any actor
+    actor:sendEvent('StartAIPackage', options)

docs/source/reference/lua-scripting/index_auxpackages.rst

@@ -0,0 +1,21 @@
+##################
+Auxiliary Packages
+##################
+
+.. include:: version.rst
+
+.. toctree::
+    :hidden:
+
+    aux_calendar <openmw_aux_calendar>
+    aux_time <openmw_aux_time>
+    aux_ui <openmw_aux_ui>
+    aux_util <openmw_aux_util>
+
+
+**Auxiliary packages**
+
+``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.
+
+.. include:: tables/aux_packages.rst

docs/source/reference/lua-scripting/index_interfaces.rst

@@ -0,0 +1,25 @@
+##########
+Interfaces
+##########
+
+.. include:: version.rst
+
+.. toctree::
+    :hidden:
+
+    activation <interface_activation>
+    ai <interface_ai>
+    animation <interface_animation>
+    camera <interface_camera>
+    controls <interface_controls>
+    gamepadcontrols <interface_gamepadcontrols>
+    item_usage <interface_item_usage>
+    mwui <interface_mwui>
+    settings <interface_settings>
+    skill_progression <interface_skill_progression>
+    ui <interface_ui>
+    crimes <interface_crimes>
+
+**Interfaces of built-in scripts**
+
+.. include:: tables/interfaces.rst

docs/source/reference/lua-scripting/index_packages.rst

@@ -0,0 +1,37 @@
+########
+Packages
+########
+
+.. include:: version.rst
+
+.. toctree::
+    :hidden:
+
+    ambient <openmw_ambient>
+    animation <openmw_animation>
+    async <openmw_async>
+    camera <openmw_camera>
+    core <openmw_core>
+    debug <openmw_debug>
+    input <openmw_input>
+    markup <openmw_markup>
+    menu <openmw_menu>
+    nearby <openmw_nearby>
+    postprocessing <openmw_postprocessing>
+    self <openmw_self>
+    storage <openmw_storage>
+    types <openmw_types>
+    ui <openmw_ui>
+    util <openmw_util>
+    vfs <openmw_vfs>
+    world <openmw_world>
+
+**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>')``.
+It can not be overloaded even if there is a lua file with the same name.
+The list of available packages is different for global and for local scripts.
+Player scripts are local scripts that are attached to a player.
+
+.. include:: tables/packages.rst

docs/source/reference/lua-scripting/overview.rst

@@ -384,8 +384,8 @@ Player scripts are local scripts that are attached to a player.
 
 .. include:: tables/packages.rst
 
-openmw_aux
+Auxiliary packages
-----------
+------------------
 
 ``openmw_aux.*`` are built-in libraries that are themselves 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.
@@ -544,7 +544,7 @@ The protection mod attaches an additional local script to every actor. The scrip
 
 In order to be able to intercept the event, the protection script should be placed in the load order below the original script.
 
-See :ref:`the list of events <Built-in events>` that are used by built-in scripts.
+See :ref:`the list of events <Events>` that are used by built-in scripts.
 
 
 Timers
@@ -618,7 +618,7 @@ An example:
         }
     }
 
-Also in `openmw_aux`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers:
+Also in `Auxiliary packages`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers:
 
 .. code-block:: Lua
 

docs/source/reference/lua-scripting/setting_renderers.rst

@@ -1,5 +1,5 @@
-Built-in Setting Renderers
+Setting Renderers
-==========================
+=================
 
 .. include:: version.rst
 

docs/source/reference/lua-scripting/tables/aux_packages.rst

@@ -1,12 +1,19 @@
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. list-table::
-| Built-in library                                        | Can be used        | Description                                                   |
+   :widths: 30 40 60
-+=========================================================+====================+===============================================================+
+   :header-rows: 1
-|:ref:`openmw_aux.calendar <Package openmw_aux.calendar>` | everywhere         | | Game time calendar                                          |
+
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - Module
-|:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
+     - Context
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Description
-|:ref:`openmw_aux.time <Package openmw_aux.time>`         | everywhere         | | Timers and game time utils                                  |
+   * - :doc:`calendar </reference/lua-scripting/openmw_aux_calendar>`
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-all|
-|:ref:`openmw_aux.ui <Package openmw_aux.ui>`             | by player and menu | | User interface utils                                        |
+     - Game time calendar
-|                                                         | scripts            |                                                               |
+   * - :doc:`util </reference/lua-scripting/openmw_aux_util>`
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-all|
+     - Miscellaneous utils
+   * - :doc:`time </reference/lua-scripting/openmw_aux_time>`
+     - |bdg-ctx-all|
+     - Timers and game time utils
+   * - :doc:`ui </reference/lua-scripting/openmw_aux_ui>`
+     - |bdg-ctx-menu| |bdg-ctx-player|
+     - User interface utils

docs/source/reference/lua-scripting/tables/interfaces.rst

@@ -1,48 +1,43 @@
 .. list-table::
-  :widths: 20 20 60
+  :widths: 30 40 60
+  :header-rows: 1
 
   * - Interface
-    - Can be used
+    - Context
     - Description
-  * - :ref:`Activation <Interface Activation>`
+  * - :doc:`Activation </reference/lua-scripting/interface_activation>`
-    - by global scripts
+    - |bdg-ctx-global|
     - Allows to extend or override built-in activation mechanics.
-  * - :ref:`AI <Interface AI>`
+  * - :doc:`ItemUsage </reference/lua-scripting/interface_item_usage>`
-    - by local scripts
+    - |bdg-ctx-global|
-    - Control basic AI of NPCs and creatures.
+    - Allows to extend or override built-in item usage mechanics.
-  * - :ref:`AnimationController <Interface AnimationController>`
+  * - :doc:`Crimes </reference/lua-scripting/interface_crimes>`
-    - by local scripts
+    - |bdg-ctx-global|
-    - Control animations of NPCs and creatures.
-  * - :ref:`Camera <Interface Camera>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in camera script
-      | without overriding the script completely.
-  * - :ref:`Controls <Interface Controls>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in script
-      | that handles player controls.
-  * - :ref:`GamepadControls <Interface GamepadControls>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in script
-      | that handles player gamepad controls.
-  * - :ref:`ItemUsage <Interface ItemUsage>`
-    - by global scripts
-    - | Allows to extend or override built-in item usage
-      | mechanics.
-  * - :ref:`SkillProgression <Interface SkillProgression>`
-    - by local scripts
-    - | Control, extend, and override skill progression of the 
-      | player.
-  * - :ref:`Settings <Interface Settings>`
-    - by player, menu, and global scripts
-    - Save, display and track changes of setting values.
-  * - :ref:`MWUI <Interface MWUI>`
-    - by player and menu scripts
-    - Morrowind-style UI templates.
-  * - :ref:`UI <Interface UI>`
-    - by player scripts
-    - | High-level UI modes interface. Allows to override parts
-      | of the interface.
-  * - :ref:`Crimes <Interface Crimes>`
-    - by global scripts
     - Commit crimes.
+  * - :doc:`AI </reference/lua-scripting/interface_ai>`
+    - |bdg-ctx-local|
+    - Control basic AI of NPCs and creatures.
+  * - :doc:`AnimationController </reference/lua-scripting/interface_animation>`
+    - |bdg-ctx-local|
+    - Control animations of NPCs and creatures.
+  * - :doc:`SkillProgression </reference/lua-scripting/interface_skill_progression>`
+    - |bdg-ctx-local|
+    - Control, extend, and override skill progression of the player.
+  * - :doc:`Camera </reference/lua-scripting/interface_camera>`
+    - |bdg-ctx-player|
+    - Allows to alter behavior of the built-in camera script without overriding the script completely.
+  * - :doc:`Controls </reference/lua-scripting/interface_controls>`
+    - |bdg-ctx-player|
+    - Allows to alter behavior of the built-in script that handles player controls.
+  * - :doc:`GamepadControls </reference/lua-scripting/interface_gamepadcontrols>`
+    - |bdg-ctx-player|
+    - Allows to alter behavior of the built-in script that handles player gamepad controls.
+  * - :doc:`UI </reference/lua-scripting/interface_ui>`
+    - |bdg-ctx-player|
+    - High-level UI modes interface. Allows to override parts of the interface.
+  * - :doc:`Settings </reference/lua-scripting/interface_settings>`
+    - |bdg-ctx-global| |bdg-ctx-menu| |bdg-ctx-player| 
+    - Save, display and track changes of setting values.
+  * - :doc:`MWUI </reference/lua-scripting/interface_mwui>`
+    - |bdg-ctx-menu| |bdg-ctx-player|
+    - Morrowind-style UI templates.

docs/source/reference/lua-scripting/tables/packages.rst

@@ -1,49 +1,64 @@
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. list-table::
-| Package                                                    | Can be used        | Description                                                   |
+   :widths: 30 40 60
-+============================================================+====================+===============================================================+
+   :header-rows: 1
-|:ref:`openmw.ambient <Package openmw.ambient>`              | by player and menu | | Controls background sounds for given player.                |
+
-|                                                            | scripts            |                                                               |
+   * - Package
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Context
-|:ref:`openmw.animation <Package openmw.animation>`          | by local and       | | Animation controls                                          |
+     - Description
-|                                                            | player scripts     |                                                               |
+   * - :doc:`core </reference/lua-scripting/openmw_core>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-all|
-|:ref:`openmw.async <Package openmw.async>`                  | everywhere         | | Timers and callbacks.                                       |
+     - Functions that are common for both global and local scripts
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`async </reference/lua-scripting/openmw_async>`
-|:ref:`openmw.camera <Package openmw.camera>`                | by player scripts  | | Controls camera.                                            |
+     - |bdg-ctx-all|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Timers and callbacks.
-|:ref:`openmw.core <Package openmw.core>`                    | everywhere         | | Functions that are common for both global and local scripts |
+   * - :ref:`interfaces <Script interfaces>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-all|
-|:ref:`openmw.debug <Package openmw.debug>`                  | by player scripts  | | Collection of debug utils.                                  |
+     - Public interfaces of other scripts.
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`markup </reference/lua-scripting/openmw_markup>`
-|:ref:`openmw.input <Package openmw.input>`                  | by player and menu | | User input.                                                 |
+     - |bdg-ctx-all|
-|                                                            | scripts            |                                                               |
+     - API to work with markup languages.
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`storage </reference/lua-scripting/openmw_storage>`
-|:ref:`openmw.interfaces <Script interfaces>`                | everywhere         | | Public interfaces of other scripts.                         |
+     - |bdg-ctx-all|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Storage API. In particular can be used to store data between game sessions.
-|:ref:`openmw.markup <Package openmw.markup>`                | everywhere         | | API to work with markup languages.                          |
+   * - :doc:`types </reference/lua-scripting/openmw_types>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-all|
-|:ref:`openmw.menu <Package openmw.menu>`                    | by menu scripts    | | Main menu functionality, such as managing game saves        |
+     - Functions for specific types of game objects.
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`util </reference/lua-scripting/openmw_util>`
-|:ref:`openmw.nearby <Package openmw.nearby>`                | by local and       | | Read-only access to the nearest area of the game world.     |
+     - |bdg-ctx-all|
-|                                                            | player scripts     |                                                               |
+     - Defines utility functions and classes like 3D vectors, that don't depend on the game world.
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`vfs </reference/lua-scripting/openmw_vfs>`
-|:ref:`openmw.postprocessing <Package openmw.postprocessing>`| by player scripts  | | Controls post-process shaders.                              |
+     - |bdg-ctx-all|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Read-only access to data directories via VFS.
-|:ref:`openmw.self <Package openmw.self>`                    | by local and       | | Full access to the object the script is attached to.        |
+   * - :doc:`world </reference/lua-scripting/openmw_world>`
-|                                                            | player scripts     |                                                               |
+     - |bdg-ctx-global|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Read-write access to the game world.
-|:ref:`openmw.storage <Package openmw.storage>`              | everywhere         | | Storage API. In particular can be used to store data        |
+   * - :doc:`menu </reference/lua-scripting/openmw_menu>`
-|                                                            |                    | | between game sessions.                                      |
+     - |bdg-ctx-menu|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Main menu functionality, such as managing game saves
-|:ref:`openmw.types <Package openmw.types>`                  | everywhere         | | Functions for specific types of game objects.               |
+   * - :doc:`animation </reference/lua-scripting/openmw_animation>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-local|
-|:ref:`openmw.ui <Package openmw.ui>`                        | by player and menu | | Controls :ref:`user interface <User interface reference>`.  |
+     - Animation controls
-|                                                            | scripts            |                                                               |
+   * - :doc:`nearby </reference/lua-scripting/openmw_nearby>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-local|
-|:ref:`openmw.util <Package openmw.util>`                    | everywhere         | | Defines utility functions and classes like 3D vectors,      |
+     - Read-only access to the nearest area of the game world.
-|                                                            |                    | | that don't depend on the game world.                        |
+   * - :doc:`self </reference/lua-scripting/openmw_self>`
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - |bdg-ctx-local|
-|:ref:`openmw.vfs <Package openmw.vfs>`                      | everywhere         | | Read-only access to data directories via VFS.               |
+     - Full access to the object the script is attached to.
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+   * - :doc:`camera </reference/lua-scripting/openmw_camera>`
-|:ref:`openmw.world <Package openmw.world>`                  | by global scripts  | | Read-write access to the game world.                        |
+     - |bdg-ctx-player|
-+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
+     - Controls camera.
+   * - :doc:`debug </reference/lua-scripting/openmw_debug>`
+     - |bdg-ctx-player|
+     - Collection of debug utils.
+   * - :doc:`postprocessing </reference/lua-scripting/openmw_postprocessing>`
+     - |bdg-ctx-player|
+     - Controls post-process shaders.
+   * - :doc:`ambient </reference/lua-scripting/openmw_ambient>`
+     - |bdg-ctx-menu| |bdg-ctx-player|
+     - Controls background sounds for given player.
+   * - :doc:`input </reference/lua-scripting/openmw_input>`
+     - |bdg-ctx-menu| |bdg-ctx-player|
+     - User input.
+   * - :doc:`ui </reference/lua-scripting/openmw_ui>`
+     - |bdg-ctx-menu| |bdg-ctx-player|
+     - Controls :ref:`user interface <UI reference>`.

docs/source/reference/lua-scripting/user_interface.rst

@@ -1,5 +1,5 @@
-User interface reference
+UI reference
-========================
+============
 
 .. include:: version.rst
 
@@ -73,63 +73,65 @@ Events
    an event-specific value, and that widget's layout table.
 | See the Widget type pages for information on what events exist, and which first argument they pass. 
 
-Widget types
-------------
-
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
-   Widget: Base widget type, all the other widgets inherit its properties and events. <widgets/widget>
+   Widget <widgets/widget>
-   Text: Displays text. <widgets/text>
+   Text <widgets/text>
-   TextEdit: Accepts text input from the user. <widgets/textedit>
+   TextEdit <widgets/textedit>
-   Image: Renders a texture. <widgets/image>
+   Image <widgets/image>
-   Flex: Aligns children in a column/row <widgets/flex>
+   Flex <widgets/flex>
-   Container: Wraps around its children <widgets/container>
+   Container <widgets/container>
 
 Example
 -------
 
-*scripts/clock.lua*
+.. tab-set::
 
-.. code-block:: Lua
+   .. tab-item:: scripts/clock.lua
 
-  local ui = require('openmw.ui')
+      .. code-block:: lua
-  local util = require('openmw.util')
-  local calendar = require('openmw_aux.calendar')
-  local time = require('openmw_aux.time')
 
-  local element = ui.create {
+         local ui = require('openmw.ui')
-    -- important not to forget the layer
+         local util = require('openmw.util')
-    -- by default widgets are not attached to any layer and are not visible
+         local calendar = require('openmw_aux.calendar')
-    layer = 'HUD',
+         local time = require('openmw_aux.time')
-    type = ui.TYPE.Text,
-    props = {
-      -- position in the top right corner
-      relativePosition = util.vector2(1, 0),
-      -- position is for the top left corner of the widget by default
-      -- change it to align exactly to the top right corner of the screen
-      anchor = util.vector2(1, 0),
-      text = calendar.formatGameTime('%H:%M'),
-      textSize = 24,
-      -- default black text color isn't always visible
-      textColor = util.color.rgb(0, 1, 0),
-    },
-  }
 
-  local function updateTime()
+         local element = ui.create {
-    -- formatGameTime uses current time by default
+            -- important not to forget the layer
-    -- otherwise we could get it by calling `core.getGameTime()`
+            -- by default widgets are not attached to any layer and are not visible
-    element.layout.props.text = calendar.formatGameTime('%H:%M')
+            layer = 'HUD',
-    -- the layout changes won't affect the widget unless we request an update
+            type = ui.TYPE.Text,
-    element:update()
+            props = {
-  end
+            -- position in the top right corner
+            relativePosition = util.vector2(1, 0),
+            -- position is for the top left corner of the widget by default
+            -- change it to align exactly to the top right corner of the screen
+            anchor = util.vector2(1, 0),
+            text = calendar.formatGameTime('%H:%M'),
+            textSize = 24,
+            -- default black text color isn't always visible
+            textColor = util.color.rgb(0, 1, 0),
+            },
+         }
 
-  -- we are showing game time in hours and minutes
+         local function updateTime()
-  -- so no need to update more often than once a game minute
+            -- formatGameTime uses current time by default
-  time.runRepeatedly(updateTime, 1 * time.minute, { type = time.GameTime })
+            -- otherwise we could get it by calling `core.getGameTime()`
+            element.layout.props.text = calendar.formatGameTime('%H:%M')
+            -- the layout changes won't affect the widget unless we request an update
+            element:update()
+         end
 
-*clock.omwscripts*
+         -- we are showing game time in hours and minutes
+         -- so no need to update more often than once a game minute
+         time.runRepeatedly(updateTime, 1 * time.minute, { type = time.GameTime })
 
-::
 
-  PLAYER: scripts/clock.lua
+   .. tab-item:: clock.omwscripts
+
+      .. code-block::
+
+         PLAYER: scripts/clock.lua
+

docs/source/reference/lua-scripting/version.rst

@@ -1,2 +1 @@
-| `OpenMW version:` |version|
+| |luaApiRevisionBadge|
-| `core.API_REVISION:` |luaApiRevision| `* <openmw_core.html##(core).API_REVISION>`_

docs/source/reference/lua-scripting/widgets/container.rst

@@ -5,4 +5,47 @@ Wraps around its children. Convenient for creating border-type templates.
 
 Relative size and position don't work for children.
 
-For template children, relative size and position depend on the children's combined size.
+For template children, relative size and position depend on the children's combined size.
+
+Properties
+----------
+
+.. list-table::
+  :header-rows: 1
+  :widths: 20 20 60
+
+  * - name
+    - type (default value)
+    - description
+  * - position
+    - util.vector2 (0, 0)
+    - | Offsets the position of the widget from its parent's
+      | top-left corner in pixels.
+  * - size
+    - util.vector2 (0, 0)
+    - Increases the widget's size in pixels.
+  * - relativePosition  
+    - util.vector2 (0, 0)
+    - | Offsets the position of the widget from its parent's
+      | top-left corner as a fraction of the parent's size.
+  * - relativeSize
+    - util.vector2 (0, 0)
+    - Increases the widget's size by a fraction of its parent's size.
+  * - anchor
+    - util.vector2 (0, 0)
+    - | Offsets the widget's position by a fraction of its size.
+      | Useful for centering or aligning to a corner.
+  * - visible
+    - boolean (true)
+    - Defines if the widget is visible
+  * - propagateEvents
+    - boolean (true)
+    - Allows base widget events to propagate to the widget's parent.
+  * - alpha
+    - number (1.0)
+    - | Set the opacity of the widget and its contents.
+      | If `inheritAlpha` is set to `true`, this becomes the maximum alpha value the widget can take.
+  * - inheritAlpha
+    - boolean (true)
+    - | Modulate `alpha` with parents `alpha`.
+      | If the parent has `inheritAlpha` set to `true`, the value after modulating is passed to the child.

docs/source/reference/lua-scripting/widgets/image.rst

@@ -1,6 +1,8 @@
 Image Widget
 ============
 
+Renders a texture.
+
 Properties
 ----------
 

docs/source/reference/lua-scripting/widgets/text.rst

@@ -1,6 +1,8 @@
 Text Widget
 ===========
 
+Displays text.
+
 Properties
 ----------
 

docs/source/reference/lua-scripting/widgets/textedit.rst

@@ -1,6 +1,8 @@
 TextEdit Widget
 ===============
 
+Accepts text input from the user.
+
 Properties
 ----------
 

docs/source/reference/lua-scripting/widgets/widget.rst

@@ -1,6 +1,8 @@
 Widget
 ======
 
+Base widget type, all the other widgets inherit its properties and events. 
+
 Properties
 ----------
 

docs/source/reference/modding/extended.rst

@@ -338,7 +338,7 @@ Also groundcover detection should be enabled via settings.cfg:
 Lua scripting
 -------------
 
-OpenMW supports Lua scripts. See :ref:`Lua scripting documentation <OpenMW Lua scripting>`.
+OpenMW supports Lua scripts. See :ref:`Lua scripting documentation <Lua scripting>`.
 It is not compatible with MWSE. A mod with Lua scripts will work only if it was developed specifically for OpenMW.
 
 Installation of a Lua mod is the same as of any other mod: add ``data=`` and ``content=`` entries to ``openmw.cfg``.

docs/source/reference/modding/index.rst

@@ -1,5 +1,5 @@
-OpenMW Modding Reference
+Modding Reference
-########################
+#################
 
 The following document is the complete reference guide to modifying, or
 modding, your OpenMW setup. It does not cover content creation itself,

docs/source/reference/modding/texture-modding/index.rst

@@ -1,6 +1,6 @@
-######################
+###############
-OpenMW Texture Modding
+Texture Modding
-######################
+###############
 
 Although texture modding requires external tools not supported by the OpenMW team,
 adding and modifying textures is an important part of content creation.

docs/source/reference/postprocessing/index.rst

@@ -1,6 +1,6 @@
-######################
+###############
-OpenMW Post Processing
+Post Processing
-######################
+###############
 
 .. toctree::
     :caption: Table of Contents

files/data/scripts/omw/ai.lua

@@ -87,7 +87,7 @@ return {
 
         --- Start new AI package.
         -- @function [parent=#AI] startPackage
-        -- @param #table options See the "Built-in AI packages" page.
+        -- @param #table options See the "AI packages" page.
         startPackage = startPackage,
 
         --- Iterate over all packages starting from the active one and remove those where `filterCallback` returns false.

files/data/scripts/omw/settings/player.lua

@@ -33,7 +33,7 @@ end
 -- @field #string name A key from the localization context
 -- @field #string description A key from the localization context (optional, can be `nil`)
 -- @field default A default value
--- @field #string renderer A renderer key (see the "Built-in Setting Renderers" page)
+-- @field #string renderer A renderer key (see the "Setting Renderers" page)
 -- @field argument An argument for the renderer
 
 return {

files/lua_api/openmw/ambient.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.ambient` controls background 2D sounds specific to a given player.
+-- Controls background 2D sounds specific to a given player.
--- Can be used only by menu scripts and local scripts that are attached to a player.
+-- @context menu|player
 -- @module ambient
 -- @usage local ambient = require('openmw.ambient')
 

files/lua_api/openmw/animation.lua

@@ -1,7 +1,8 @@
 ---
--- `openmw.animation` defines functions that allow control of character animations.
+-- Defines functions that allow control of character animations.
 -- Note that for some methods, such as @{openmw.animation#playBlended} you should use the associated methods on the 
 -- [AnimationController](interface_animation.html) interface rather than invoking this API directly.
+-- @context local
 -- @module animation
 -- @usage local anim = require('openmw.animation')
 

files/lua_api/openmw/async.lua

@@ -1,6 +1,7 @@
 ---
--- `openmw.async` contains timers and coroutine utilities. All functions require
+-- Contains timers and coroutine utilities. All functions require
 -- the package itself as a first argument.
+-- @context global|menu|local|player
 -- @module async
 -- @usage local async = require('openmw.async')
 

files/lua_api/openmw/camera.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.camera` controls camera.
+-- Controls camera.
--- Can be used only by player scripts.
+-- @context player
 -- @module camera
 -- @usage local camera = require('openmw.camera')
 

files/lua_api/openmw/core.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.core` defines functions and types that are available in local,
+-- Defines functions and types that are available in local, global and menu scripts.
--- global and menu scripts.
+-- @context global|menu|local|player
 -- @module core
 -- @usage local core = require('openmw.core')
 

files/lua_api/openmw/debug.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.debug` is an interface to the engine debug utils.
+-- Provides an interface to the engine debug utils.
--- Can be used only by local scripts, that are attached to a player.
+-- @context player
 -- @module Debug
 -- @usage local debug = require('openmw.debug')
 

files/lua_api/openmw/input.lua

@@ -1,9 +1,9 @@
 ---
--- `openmw.input` can be used only in menu scripts and scripts attached to a player.
 -- Most mods should prefer to use the actions/triggers API over the direct input device methods.
 -- Actions have one value on each frame (resolved just before the `onFrame` engine handler),
 --  while Triggers don't have a value, but can occur multiple times on each frame.
 -- Prefer to use built-in methods of binding actions, such as the [inputBinding setting renderer](setting_renderers.html#inputbinding)
+-- @context menu|player
 -- @module input
 -- @usage local input = require('openmw.input')
 -- -- Example of Action usage

files/lua_api/openmw/interfaces.lua

@@ -1,4 +1,5 @@
 ---
+-- @context global|menu|local|player
 -- @module interfaces
 -- @usage local I = require('openmw.interfaces')
 

files/lua_api/openmw/markup.lua

@@ -1,5 +1,6 @@
 ---
--- `openmw.markup` allows to work with markup languages.
+-- Allows to work with markup languages.
+-- @context global|menu|local|player
 -- @module markup
 -- @usage local markup = require('openmw.markup')
 

files/lua_api/openmw/menu.lua

@@ -1,5 +1,6 @@
 ---
--- `openmw.menu` can be used only in menu scripts.
+-- Provides interfaces to interact with menu elements.
+-- @context menu
 -- @module menu
 -- @usage local menu = require('openmw.menu')
 

files/lua_api/openmw/nearby.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.nearby` provides read-only access to the nearest area of the game world.
+-- Provides read-only access to the nearest area of the game world.
--- Can be used only from local scripts.
+-- @context local
 -- @module nearby
 -- @usage local nearby = require('openmw.nearby')
 

files/lua_api/openmw/postprocessing.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.postprocessing` is an interface to postprocessing shaders.
+-- Provides an interface to postprocessing shaders.
--- Can be used only by local scripts, that are attached to a player.
+-- @context player
 -- @module postprocessing
 -- @usage local postprocessing = require('openmw.postprocessing')
 

files/lua_api/openmw/self.lua

@@ -1,6 +1,7 @@
 ---
--- `openmw.self` provides full access to the object the script is attached to.
+-- Provides full access to the object the script is attached to.
--- Can be used only from local scripts. All fields and function of `GameObject` are also available for `openmw.self`.
+-- All fields and function of `GameObject` are also available for `openmw.self`.
+-- @context local
 -- @module Self
 -- @extends openmw.core#GameObject
 -- @usage local self = require('openmw.self')

files/lua_api/openmw/storage.lua

@@ -1,5 +1,6 @@
 ---
--- `openmw.storage` contains functions to work with permanent Lua storage.
+-- Contains functions to work with permanent Lua storage.
+-- @context global|menu|local|player
 -- @module storage
 -- @usage
 -- local storage = require('openmw.storage')

files/lua_api/openmw/types.lua

@@ -1,5 +1,6 @@
 ---
--- `openmw.types` defines functions for specific types of game objects.
+-- Defines functions for specific types of game objects.
+-- @context global|menu|local|player
 -- @module types
 -- @usage local types = require('openmw.types')
 

files/lua_api/openmw/ui.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.ui` controls user interface.
+-- Controls user interface.
--- Can be used only by menu scripts and local scripts, that are attached to a player.
+-- @context menu|player
 -- @module ui
 -- @usage
 -- local ui = require('openmw.ui')

files/lua_api/openmw/util.lua

@@ -1,5 +1,6 @@
 ---
--- `openmw.util` defines utility functions and classes like 3D vectors, that don't depend on the game world.
+-- Defines utility functions and classes like 3D vectors, that don't depend on the game world.
+-- @context global|menu|local|player
 -- @module util
 -- @usage local util = require('openmw.util')
 

files/lua_api/openmw/vfs.lua

@@ -1,6 +1,7 @@
 ---
--- `openmw.vfs` provides read-only access to data directories via VFS.
+-- Provides read-only access to data directories via VFS.
 -- Interface is very similar to "io" library.
+-- @context global|menu|local|player
 -- @module vfs
 -- @usage local vfs = require('openmw.vfs')
 

files/lua_api/openmw/world.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.world` is an interface to the game world for global scripts.
+-- Provides an interface to the game world for global scripts.
--- Can not be used from local scripts.
+-- @context global
 -- @module world
 -- @usage local world = require('openmw.world')