Quickstart

Declaring objects

Use lua:module to indicate which module you’re documenting. After it, use lua:data, lua:function, lua:class, and others to document module’s contents.

.. lua:module:: soundboard

.. lua:class:: Sound

   A sound that can be played by the sound board.

```{lua:module} soundboard
```

```{lua:class} Sound
A sound that can be played by the sound board.
```
Example output
class soundboard.Sound

A sound that can be played by the sound board.

Tip

Setting the primary domain

You can avoid prefixing directives and roles with lua: if you set Lua as your primary domain. For this, declare primary_domain in your conf.py:

primary_domain = "lua"

This will significantly reduce boilerplate in documentation:

Cross-reference to :lua:`Sound`.

.. class:: Sound

   A sound that can be played by the sound board.

Cross-reference to {lua}`Sound`.

```{class} Sound
A sound that can be played by the sound board.
```
Setting up primary domain in EmmyLua

To enable accurate Go To Definition behavior for comments, add rstPrimaryDomain setting to your .emmyrc.json:

{
   "diagnostics": {
      "enables": ["unknown-doc-tag"]
   },
   "doc": {
      "knownTags": ["doctype", "doc"],
      "syntax": "rst",
      "rstPrimaryDomain": "lua"
   }
}

{
   "diagnostics": {
      "enables": ["unknown-doc-tag"]
   },
   "doc": {
      "knownTags": ["doctype", "doc"],
      "syntax": "myst",
      "rstPrimaryDomain": "lua"
   }
}

Cross-referencing objects

Reference documented entities using the lua:data, lua:func, and lua:class roles:

Here's a reference to the :lua:class:`soundboard.Sound` class.

Here's a reference to the {lua:class}`soundboard.Sound` class.
Example output

Here’s a reference to the soundboard.Sound class.

Tip

Setting the default role

When you use backticks without explicitly specifying a role, Sphinx uses the default role to resolve it. Setting lua:obj as the default role can reduce boilerplate in documentation.

In conf.py, declare default_role:

default_role = "lua:obj"

Now, you can reference any object with just backticks:

Reference to a `logging.Logger.info`.

MySt plugin doesn’t support default roles. However, if you set lua as the primary domain, you’ll be able to use lua:lua like so:

Reference to a {lua}`logging.Logger.info`.
Setting up default role in EmmyLua

To enable accurate Go To Definition behavior for comments, add rstDefaultRole setting to your .emmyrc.json:

{
   "diagnostics": {
      "enables": ["unknown-doc-tag"]
   },
   "doc": {
      "knownTags": ["doctype", "doc"],
      "syntax": "rst",
      "rstDefaultRole": "lua:obj"
   }
}

{
   "diagnostics": {
      "enables": ["unknown-doc-tag"]
   },
   "doc": {
      "knownTags": ["doctype", "doc"],
      "syntax": "myst",
      "rstDefaultRole": "lua:obj"
   }
}

Automatic documentation generation

Use lua:autoobject to extract documentation from source code. Its options are similar to the ones used by python autodoc:

.. lua:autoobject:: logging.Logger
   :members:

```{lua:autoobject} logging.Logger
:members:
```
Example output
class logging.Logger
class ctor logging.Logger(name: string, level?: logging.Level)

An object for logging messages.

Parameters:

  • name (string) – name of the logger, will be added to every message.

  • level? (logging.Level) – level of the logger, equals to LOG_LEVEL by default.

debug(self, msg: string, ...: any)

Print a debug message.

Parameters:

  • msg (string) – message format string, will be processed by string.format.

  • ... (any) – parameters for message formatting.

info(self, msg: string, ...: any)

Print an info message.

Parameters:

  • msg (string) – message format string, will be processed by string.format.

  • ... (any) – parameters for message formatting.

warning(self, msg: string, ...: any)

Print a warning message.

Parameters:

  • msg (string) – message format string, will be processed by string.format.

  • ... (any) – parameters for message formatting.

error(self, msg: string, ...: any)

Print an error message.

Parameters:

  • msg (string) – message format string, will be processed by string.format.

  • ... (any) – parameters for message formatting.