add docutils section

Author: chrisjsewell

docs/computation/execute.md

@@ -4,6 +4,7 @@ kernelspec:
   name: python3
 ---
 
+(execute/intro)=
 # Execute and cache
 
 MyST-NB can automatically run and cache notebooks contained in your project using [jupyter-cache].

docs/conf.py

@@ -277,5 +277,31 @@ def run(self):
             self.state.nested_parse(text, 0, node)
             return node.children
 
+    class DocutilsCliHelpDirective(SphinxDirective):
+        """Directive to print the docutils CLI help."""
+
+        has_content = False
+        required_arguments = 0
+        optional_arguments = 0
+        final_argument_whitespace = False
+        option_spec = {}
+
+        def run(self):
+            """Run the directive."""
+            import io
+
+            from docutils import nodes
+            from docutils.frontend import OptionParser
+
+            from myst_nb.docutils_ import Parser as DocutilsParser
+
+            stream = io.StringIO()
+            OptionParser(
+                components=(DocutilsParser,),
+                usage="mystnb-docutils-<writer> [options] [<source> [<destination>]]",
+            ).print_help(stream)
+            return [nodes.literal_block("", stream.getvalue())]
+
     app.add_directive("myst-config", MystConfigDirective)
     app.add_directive("mystnb-config", MystNbConfigDirective)
+    app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)

docs/docutils.md

@@ -0,0 +1,82 @@
+(render/single-page)=
+# Single page builds
+
+```{versionadded} 0.14.0
+```
+
+Sphinx, and thus MyST-NB, is built on top of the [Docutils](https://docutils.sourceforge.io/docs/) 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:
+
+```console
+$ 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](https://docutils.sourceforge.io/docs/user/tools.html), and so follow the same argument and options structure, included many of the MyST NB specific options detailed in the [](config/intro) section.
+
+:::{dropdown}  Shared Docutils CLI Options
+```{docutils-cli-help}
+```
+:::
+
+The CLI commands can also utilise the [`docutils.conf` configuration file](https://docutils.sourceforge.io/docs/user/config.html) to configure the behaviour of the CLI commands. For example:
+
+```ini
+# 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](https://docutils.sourceforge.io/docs/api/publisher.html):
+
+```python
+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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include):
+
+```rst
+.. include:: include.ipynb
+   :parser: myst_nb.docutils_
+```
+
+```{important}
+The `parser` option requires `docutils>=0.17`
+```

docs/index.md

@@ -27,7 +27,7 @@ sd_hide_title: true
 ```{rubric} Jupyter Notebook Publishing
 ```
 
-A Docutils and Sphinx extension for compiling Jupyter Notebooks into high quality documentation formats.
+A Sphinx and Docutils extension for compiling Jupyter Notebooks into high quality documentation formats.
 
 ```{button-ref} quickstart
 :ref-type: doc
@@ -58,14 +58,14 @@ Use MyST Markdown syntax to support technical authoring features such as cross-r
 :::
 
 :::{grid-item-card} {material-regular}`published_with_changes;2em` Compute
-:link: computation/index
-:link-type: doc
+:link: execute/intro
+:link-type: ref
 
 Generate dynamic outputs using Jupyter kernels, with configurable execution handling.\
 Cache execution outputs, for fast re-builds.
 
 +++
-[Learn more »](computation/index)
+[Learn more »](execute/intro)
 :::
 
 :::{grid-item-card} {material-regular}`preview;2em` Render
@@ -110,6 +110,7 @@ authoring/index
 computation/index
 render/index
 configuration
+docutils
 ```
 
 ```{toctree}

docs/render/docutils.md

@@ -9,5 +9,4 @@ format_outputs
 hiding
 glue
 interactive
-docutils
 ```