Skip to content

Latest commit

 

History

History
82 lines (63 loc) · 2.71 KB

docutils.md

File metadata and controls

82 lines (63 loc) · 2.71 KB
Raw

(render/single-page)=

Single page builds

Sphinx, and thus MyST-NB, is built on top of the Docutils package. MyST-NB offers a renderer, parser and CLI-interface for working directly with Docutils, independent of Sphinx, as described below.

:::{note} Since these tools are independent of Sphinx, this means they cannot parse any Sphinx or Sphinx extensions specific roles or directives. :::

On installing MyST-NB, the following CLI-commands are made available:

  • mystnb-docutils-html: converts notebooks to HTML
  • mystnb-docutils-html5: converts notebooks to HTML5
  • mystnb-docutils-latex: converts notebooks to LaTeX
  • mystnb-docutils-xml: converts notebooks to docutils-native XML
  • mystnb-docutils-pseudoxml: converts notebooks to pseudo-XML (to visualise the AST structure)

Each command can be piped stdin or take a file path as an argument:

$ mystnb-docutils-html --help
$ mystnb-docutils-html --nb-execution-mode="off" hello-world.ipynb
$ mystnb-docutils-html --nb-read-as-md="yes" hello-world.md

The commands are based on the Docutils Front-End Tools, and so follow the same argument and options structure, included many of the MyST NB specific options detailed in the section.

:::{dropdown} Shared Docutils CLI Options

:::

The CLI commands can also utilise the docutils.conf configuration file to configure the behaviour of the CLI commands. For example:

# These entries affect all processing:
[general]
nb_execution_mode: off

# These entries affect specific HTML output:
[html writers]
embed-stylesheet: no

[html5 writer]
stylesheet-dirs: path/to/html5_polyglot/
stylesheet-path: minimal.css, responsive.css

You can also use the {py:class}myst_nb.docutils_.Parser class programmatically with the Docutils publisher API:

from docutils.core import publish_string
from nbformat import writes
from nbformat.v4 import new_notebook
from myst_nb.docutils_ import Parser

source = writes(new_notebook())
output = publish_string(
    source=source,
    writer_name="html5",
    settings_overrides={
        "nb_execution_mode": "off",
        "embed_stylesheet": False,
    },
    parser=Parser(),
)

Finally, you can include MyST Markdown files within a RestructuredText file, using the include directive:

.. include:: include.ipynb
   :parser: myst_nb.docutils_
The `parser` option requires `docutils>=0.17`