code_and_apis.md

(syntax/code-blocks)=

Source code and APIs

Basic block syntax highlighting

Code blocks contain a language identifier, which is used to determine the language of the code. This language is used to determine the syntax highlighting, using an available pygments lexer.

:::{myst-example}

from a import b
c = "string"

:::

::::{admonition} Adding a language lexer :class: tip dropdown You can create and register your own lexer, using the pygments.lexers entry point, or within a sphinx extension, with the app.add_lexer method. ::::

::::{admonition} Show backticks inside raw markdown blocks :class: tip dropdown

If you'd like to show backticks inside of your markdown, you can do so by nesting them in backticks of a greater length. Markdown will treat the outer-most backticks as the edges of the "raw" block and everything inside will show up. For example:

:::{myst-example} `hi`

```
hi
```

:::

::::

Inline syntax highlighting

The attrs_inline extension can be used to apply syntax highlighting to inline code:

:::{myst-example} Inline Python code a = "b"{l=python} :::

Numbering and highlighting lines

To set a global default for line numbering, per lexer name, the myst_number_code_blocks configuration option can be used. For example, using:

myst_number_code_blocks = ["typescript"]

Will number all code blocks with the typescript lexer by default.

:::{myst-example}

type MyBool = true | false;

interface User {
  name: string;
  id: number;
}

:::

To apply numbering and highlighting to a specific code block, the attrs_block extension can be used:

:::{myst-example} {lineno-start=1 emphasize-lines="2,3"}

a = 1
b = 2
c = 3

:::

Adding a caption

With the code-block {{directive}}, a caption can be added to a code blocks, as well as other options:

:::{myst-example}

:caption: This is a caption
:emphasize-lines: 2,3
:lineno-start: 1

a = 1
b = 2
c = 3

:::

The following options are recognized:

:::{admonition} Code block options :class: hint dropdown

linenos : flag : Enable to generate line numbers for the code block

lineno-start : integer : The starting line number for the code block (linenos is automatically enabled)

emphasize-lines : comma-separated list of integers : Highlight the specified lines

caption : string : The caption for the code block

force : flag : Allow minor errors on highlighting to be ignored

name : string : The name of the code block, which can be referenced elsewhere in the document

class : string : The class to apply to the code block

The [Sphinx documentation](inv:sphinx#code-block)

:::

(syntax/literalinclude)=

Including code from files

Longer pieces of code can be included from files using the literalinclude {{directive}}:

:::{myst-example}

:::

The file name is usually relative to the current file’s path. However, if it is absolute (starting with /), it is relative to the top source directory.

To select only a sub-section of the file, the lines, pyobject or start-after and end-before options can be used:

:::{myst-example}

:start-after: start example
:end-before: end example

:::

The [Sphinx documentation](inv:sphinx#literalinclude)

(syntax/apis)=

Documenting whole APIs

Sphinx and MyST provide means to analyse source code and automatically generate documentation and referenceable links for APIs.

sphinx.ext.autodoc can be used (see below), however, it is not inherently compatible with MyST Markdown, and so the sphinx-autodoc2 extension is recommended.

(syntax/apis/sphinx-autodoc2)=

sphinx-autodoc2

sphinx-autodoc2 is an extension for Sphinx that provides an integrated means to document Python APIs.

As opposed to sphinx.ext.autodoc, sphinx-autodoc2 performs static (rather than dynamic) analysis of the source code, integrates full package documenting, and also allows for docstrings to be written in both RestructureText and MyST.

The sphinx-autodoc2's auto_mode config variable (which per default is True) will automatically generate the full API documentation, as shown project:/apidocs/index.rst.

Alternatively, the autodoc2-object directive can be used to generate documentation for a single object. To embed in a MyST document the MyST render_plugin should be specified, for example:

```{autodoc2-object} myst_parser.sphinx_ext.main.setup_sphinx
render_plugin = "myst"
no_index = true
```

This can be referenced elsewhere in the document using the :py:obj: role, or a # link (see cross-referencing).

- {py:obj}`myst_parser.sphinx_ext.main.setup_sphinx`
- [](#myst_parser.sphinx_ext.main.setup_sphinx)

Additionally, summaries of multiple objects can be generated using the autodoc2-summary directive:

```{autodoc2-summary}
:renderer: myst

~myst_parser.sphinx_ext.main.setup_sphinx
~myst_parser.sphinx_ext.main.create_myst_config
```

Using MyST docstrings

sphinx-autodoc2 can be configured to use MyST docstrings (rather than RestructureText), for the entire project or select objects, by setting the autodoc2_docstring_parser_regexes configuration option:

autodoc2_docstring_parser_regexes = [
    # this will render all docstrings as Markdown
    (r".*", "myst"),
    # this will render select docstrings as Markdown
    (r"mypackage\.mymodule\..*", "myst"),
]

For example:

```{autodoc2-object} myst_parser.setup
render_plugin = "myst"
no_index = true
docstring_parser_regexes = [
    ["myst_parser\\.setup", "myst"],
]
```

(syntax/apis/sphinx-autodoc)=

sphinx.ext.autodoc

Sphinx extension autodoc also can generate documentation for Python objects. However, because it is hard-coded to generate RestructureText, the special eval-rst directive needs to be used:

```{eval-rst}
.. autofunction:: myst_parser.sphinx_ext.main.setup_sphinx
    :noindex:
```

Summaries can also be generated with autosummary:

```{eval-rst}
.. autosummary::
    :nosignatures:

    myst_parser.sphinx_ext.main.setup_sphinx
    myst_parser.sphinx_ext.main.create_myst_config
```