🙈 Notebook Cell Tags Documentation (#1750)

.changeset/clean-meals-scream.md

@@ -0,0 +1,6 @@
+---
+"myst-execute": patch
+"myst-common": patch
+---
+
+Use NotebookCellTags for raises-exception and skip-execution

.changeset/gorgeous-trainers-fetch.md

@@ -0,0 +1,9 @@
+---
+"myst-to-typst": patch
+"myst-to-docx": patch
+"myst-to-jats": patch
+"myst-to-tex": patch
+"myst-to-md": patch
+---
+
+Update static exports to hide hidden code cells and blocks.

docs/myst.yml

@@ -108,6 +108,7 @@ project:
         - file: reuse-jupyter-outputs.md
         - file: interactive-notebooks.ipynb
         - file: integrating-jupyter.md
+        - file: notebook-configuration.md
     - title: Websites
       children:
         - file: website-templates.md

docs/notebook-configuration.md

@@ -0,0 +1,51 @@
+---
+title: Notebook Configuration
+---
+
+In Jupyter Notebooks you can add cell level configuration by specifying **tags** in the cell metadata.
+There are also global controls in the [project settings](#project-settings).
+
+(notebook-cell-tags)=
+
+### Notebook Cell Tags
+
+Tags are a list of strings under the `tags` key in the cell metadata, which can be set in JupyterLab, VSCode or in a {myst:directive}`code-cell` directive.
+
+In the JSON representation of a jupyter notebook these look like:
+
+```json
+{
+  "cell_type": "code",
+  "source": ["print('hello world')"],
+  "metadata": {
+    "tags": ["my-tag1", "my-tag2"]
+  }
+}
+```
+
+In Markdown of a jupyter notebook these look like:
+
+````markdown
+```{code-cell} python
+:tags: remove-input
+print("This will show output with no input!")
+```
+````
+
+:::{table} Notebook cell tags with special meanings
+:label: tbl:notebook-cell-tags
+
+| Tag                | Description                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `remove-cell`      | Remove the cell from the rendered output.                                                                      |
+| `remove-input`     | Remove the code cell input/source from the rendered output.                                                    |
+| `remove-output`    | Remove the code cell output from the rendered output.                                                          |
+| `hide-cell`        | Hides the cell from the rendered output.                                                                       |
+| `hide-input`       | Hides the code cell input/source from the rendered output.                                                     |
+| `hide-output`      | Hides the code cell output from the rendered output.                                                           |
+| `remove-stderr`    | Remove the code cell output stderr from the rendered output. See also [project config](#setting:output_stderr) |
+| `remove-stdout`    | Remove the code cell output stdout from the rendered output. See also [project config](#setting:output_stdout) |
+| `skip-execution`   | Skip this cell, when executing the notebook                                                                    |
+| `raises-exception` | Expect the code cell to raise an Exception (and continue execution)                                            |
+
+:::

docs/notebooks-with-markdown.md

@@ -54,7 +54,7 @@ After we declare the frontmatter, the contents of each {myst:directive}`code-cel
 Furthermore, you can build MyST Markdown content with other programming languages like JavaScript, R, and Julia by installing the corresponding kernel. For example, to build a page that uses JavaScript in the {myst:directive}`code-cell`, we could:
 
 1. Install a JavaScript kernel, e.g. [ijavascript](https://github.com/n-riesco/ijavascript).
-2. Retrieve the kernel name with `jupyter kernelspec list`.  
+2. Retrieve the kernel name with `jupyter kernelspec list`.
    In the default installation, the kernel name is `javascript`.
 3. Set the kernelspec in your document's frontmatter:
    ```yaml
@@ -112,7 +112,7 @@ print(phrase)
 You can add tags to the {myst:directive}`code-cell` directive.
 They will be parsed and used in the same way that cell tag metadata is used in `.ipynb` files.
 
-For example, the following code defines a `remove-input` tag:
+For example, the following code defines a `remove-input` tag (See all [notebook tag options](#tbl:notebook-cell-tags)):
 
 ````markdown
 ```{code-cell} python

docs/settings.md

@@ -5,6 +5,8 @@ description: Project and page settings for MyST
 
 The `settings` field in the project or page frontmatter allows you to change how the parsing, transforms, plugins, or other behaviors of mystmd.
 
+(project-settings)=
+
 ## Available settings fields
 
 (setting:output_stderr)=
@@ -16,6 +18,8 @@ output_stderr
     - `"remove-warn"` or `"remove-error"`: remove all stderr, and log a warning or error
     - `"warn"` or "error": log a warning or error if a stderr is found
 
+: Can be controlled or overridden by a [notebook cell tag](#tbl:notebook-cell-tags).
+
 (setting:output_stdout)=
 output_stdout
 : Remove, warn or error on stdout outputs. (e.g. long text outputs, like text-based progress bars)
@@ -25,6 +29,8 @@ output_stdout
     - `"remove-warn"` or `"remove-error"`: remove all stdout, and log a warning or error
     - `"warn"` or "error": log a warning or error if a stdout is found
 
+: Can be controlled or overridden by a [notebook cell tag](#tbl:notebook-cell-tags).
+
 (setting:output_matplotlib_strings)=
 output_matplotlib_strings
 : Remove, warn or error on matplotlib strings outputs. (e.g. `<Figure size 720x576 with 1 Axes>` or `Text(0.5, 0.98, 'Test 1')`). These can also be suppressed by ending your cell content with a semicolon in Jupyter Notebooks. The default is to remove these and warn (`"remove-warn"`).

packages/myst-common/src/types.ts

@@ -41,6 +41,8 @@ export enum NotebookCellTags {
   'removeCell' = 'remove-cell',
   'removeInput' = 'remove-input',
   'removeOutput' = 'remove-output',
+  'skipExecution' = 'skip-execution',
+  'raisesException' = 'raises-exception',
 }
 
 export type References = {

packages/myst-execute/src/execute.ts

@@ -5,7 +5,7 @@ import type { Kernel, KernelMessage, Session, SessionManager } from '@jupyterlab
 import type { Block, Code, InlineExpression, Output } from 'myst-spec-ext';
 import type { IOutput } from '@jupyterlab/nbformat';
 import type { GenericNode, GenericParent, IExpressionResult, IExpressionError } from 'myst-common';
-import { NotebookCell, fileError } from 'myst-common';
+import { NotebookCell, NotebookCellTags, fileError } from 'myst-common';
 import type { VFile } from 'vfile';
 import path from 'node:path';
 import assert from 'node:assert';
@@ -175,15 +175,15 @@ function isCellBlock(node: GenericNode): node is CodeBlock {
  * @param node block to test
  */
 function codeBlockRaisesException(node: CodeBlock) {
-  return !!node.data?.tags?.includes?.('raises-exception');
+  return !!node.data?.tags?.includes?.(NotebookCellTags.raisesException);
 }
 /**
  * Return true if the given code block should not be executed
  *
  * @param node block to test
  */
 function codeBlockSkipsExecution(node: CodeBlock) {
-  return !!node.data?.tags?.includes?.('skip-execution');
+  return !!node.data?.tags?.includes?.(NotebookCellTags.skipExecution);
 }
 
 /**

packages/myst-to-docx/src/schema.ts

@@ -85,7 +85,7 @@ const paragraph: Handler<ParagraphNode> = (state, node) => {
 };
 
 const block: Handler<Block> = (state, node) => {
-  if (node.visibility === 'remove') return;
+  if (node.visibility === 'remove' || node.visibility === 'hide') return;
   const metadataTags = getMetadataTags(node);
   if (metadataTags.includes('page-break') || metadataTags.includes('new-page')) {
     state.current.push(new PageBreak());

packages/myst-to-jats/src/index.ts

@@ -306,7 +306,7 @@ const handlers: Handlers = {
     state.renderInline(node, 'title');
   },
   block(node, state) {
-    if (node.visibility === 'remove') return;
+    if (node.visibility === 'remove' || node.visibility === 'hide') return;
     state.renderChildren(node);
   },
   blockquote(node, state) {

packages/myst-to-md/src/misc.ts

@@ -10,7 +10,7 @@ function comment(node: any, _: Parent, state: State): string {
 }
 
 function block(node: any, _: Parent, state: State, info: Info): string {
-  if (node.visibility === 'remove') return '';
+  if (node.visibility === 'remove' || node.visibility === 'hide') return '';
   const meta = node.meta ? ` ${node.meta}` : '';
   const content = state.containerFlow(node, info);
   return `+++${meta}\n${content}`;

packages/myst-to-tex/src/index.ts

@@ -164,7 +164,7 @@ const handlers: Record<string, Handler> = {
       state.write('\\end{frame}\n\n');
       return;
     }
-    if (node.visibility === 'remove') return;
+    if (node.visibility === 'remove' || node.visibility === 'hide') return;
     if (metadataTags.includes('no-tex')) return;
     if (metadataTags.includes('no-pdf')) return;
     if (metadataTags.includes('new-page')) {
@@ -202,9 +202,7 @@ const handlers: Record<string, Handler> = {
     state.renderChildren(node, true);
   },
   code(node: Code, state) {
-    if (node.visibility === 'remove') {
-      return;
-    }
+    if (node.visibility === 'remove' || node.visibility === 'hide') return;
     addIndexEntries(node, state);
     let start = '\\begin{verbatim}\n';
     let end = '\n\\end{verbatim}';

packages/myst-to-typst/src/index.ts

@@ -145,7 +145,7 @@ const handlers: Record<string, Handler> = {
     const metadataTags = getMetadataTags(node);
     if (metadataTags.includes('no-typst')) return;
     if (metadataTags.includes('no-pdf')) return;
-    if (node.visibility === 'remove') return;
+    if (node.visibility === 'remove' || node.visibility === 'hide') return;
     if (metadataTags.includes('page-break') || metadataTags.includes('new-page')) {
       state.write('#pagebreak(weak: true)\n');
     }
@@ -183,9 +183,7 @@ const handlers: Record<string, Handler> = {
     state.renderChildren(node);
   },
   code(node: Code, state) {
-    if (node.visibility === 'remove') {
-      return;
-    }
+    if (node.visibility === 'remove' || node.visibility === 'hide') return;
     let ticks = '```';
     while (node.value.includes(ticks)) {
       ticks += '`';