🙈 Notebook Cell Tags Documentation

See also jupyter-book/myst-theme#517

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,59 @@
+---
+title: Notebook Configuration
+---
+
+As a convenience for users in Jupyter interfaces, some cell level configuration can be achieved by specifying tags in the cell metadata via tags
+
+(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) |
+
+:::
+
+:::{warning} Not Yet implemented
+
+For code execution, these tags are provided:
+
+| Tag                | Description                                                         |
+| ------------------ | ------------------------------------------------------------------- |
+| `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

@@ -16,6 +16,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 +27,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"`).