From 7837f4d31c0f80ae176353a42f63546d16714ac7 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Jan 2025 15:20:41 -0700 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=99=88=20Notebook=20Cell=20Tags=20Doc?= =?UTF-8?q?umentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See also jupyter-book/myst-theme#517 --- docs/myst.yml | 1 + docs/notebook-configuration.md | 59 +++++++++++++++++++++++++++++++++ docs/notebooks-with-markdown.md | 4 +-- docs/settings.md | 4 +++ 4 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 docs/notebook-configuration.md diff --git a/docs/myst.yml b/docs/myst.yml index 467678052..375e6c294 100644 --- a/docs/myst.yml +++ b/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 diff --git a/docs/notebook-configuration.md b/docs/notebook-configuration.md new file mode 100644 index 000000000..3d924cfdb --- /dev/null +++ b/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) | + +::: diff --git a/docs/notebooks-with-markdown.md b/docs/notebooks-with-markdown.md index 27c0a7a50..08e6e52d4 100644 --- a/docs/notebooks-with-markdown.md +++ b/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 diff --git a/docs/settings.md b/docs/settings.md index 7ce7a7e76..6a7334440 100644 --- a/docs/settings.md +++ b/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. `
` 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"`). From 56c7ece66e9676c98bfdbd424b7c382cafc574ef Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Jan 2025 15:31:16 -0700 Subject: [PATCH 2/5] Use NotebookCellTags for raises-exception and skip-execution --- docs/notebook-configuration.md | 36 +++++++++++----------------- docs/settings.md | 2 ++ packages/myst-common/src/types.ts | 2 ++ packages/myst-execute/src/execute.ts | 6 ++--- 4 files changed, 21 insertions(+), 25 deletions(-) diff --git a/docs/notebook-configuration.md b/docs/notebook-configuration.md index 3d924cfdb..ce9529416 100644 --- a/docs/notebook-configuration.md +++ b/docs/notebook-configuration.md @@ -2,7 +2,8 @@ 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 +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)= @@ -34,26 +35,17 @@ 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) | +| 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) | ::: diff --git a/docs/settings.md b/docs/settings.md index 6a7334440..31ca3296a 100644 --- a/docs/settings.md +++ b/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)= diff --git a/packages/myst-common/src/types.ts b/packages/myst-common/src/types.ts index 0231d1927..4e0340e90 100644 --- a/packages/myst-common/src/types.ts +++ b/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 = { diff --git a/packages/myst-execute/src/execute.ts b/packages/myst-execute/src/execute.ts index 5f14286c8..e97dcfad4 100644 --- a/packages/myst-execute/src/execute.ts +++ b/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,7 +175,7 @@ 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 @@ -183,7 +183,7 @@ function codeBlockRaisesException(node: CodeBlock) { * @param node block to test */ function codeBlockSkipsExecution(node: CodeBlock) { - return !!node.data?.tags?.includes?.('skip-execution'); + return !!node.data?.tags?.includes?.(NotebookCellTags.skipExecution); } /** From 08603cfe5b4d52dbcf1ddf7216f2edbc3ffbc301 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Jan 2025 15:31:22 -0700 Subject: [PATCH 3/5] changeset --- .changeset/clean-meals-scream.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/clean-meals-scream.md diff --git a/.changeset/clean-meals-scream.md b/.changeset/clean-meals-scream.md new file mode 100644 index 000000000..7497bcf8e --- /dev/null +++ b/.changeset/clean-meals-scream.md @@ -0,0 +1,6 @@ +--- +"myst-execute": patch +"myst-common": patch +--- + +Use NotebookCellTags for raises-exception and skip-execution From 5b376a1fb5ab84aa133191b11c05959140cebf44 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Jan 2025 15:42:32 -0700 Subject: [PATCH 4/5] Hide hidden outputs/code/blocks for static exports --- packages/myst-to-docx/src/schema.ts | 2 +- packages/myst-to-jats/src/index.ts | 2 +- packages/myst-to-md/src/misc.ts | 2 +- packages/myst-to-tex/src/index.ts | 6 ++---- packages/myst-to-typst/src/index.ts | 6 ++---- 5 files changed, 7 insertions(+), 11 deletions(-) diff --git a/packages/myst-to-docx/src/schema.ts b/packages/myst-to-docx/src/schema.ts index 395728de5..ad48bead7 100644 --- a/packages/myst-to-docx/src/schema.ts +++ b/packages/myst-to-docx/src/schema.ts @@ -85,7 +85,7 @@ const paragraph: Handler = (state, node) => { }; const block: Handler = (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()); diff --git a/packages/myst-to-jats/src/index.ts b/packages/myst-to-jats/src/index.ts index 26c4e55ff..05ec2ce81 100644 --- a/packages/myst-to-jats/src/index.ts +++ b/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) { diff --git a/packages/myst-to-md/src/misc.ts b/packages/myst-to-md/src/misc.ts index ae1177339..a6ff9045b 100644 --- a/packages/myst-to-md/src/misc.ts +++ b/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}`; diff --git a/packages/myst-to-tex/src/index.ts b/packages/myst-to-tex/src/index.ts index 370028582..26893633a 100644 --- a/packages/myst-to-tex/src/index.ts +++ b/packages/myst-to-tex/src/index.ts @@ -164,7 +164,7 @@ const handlers: Record = { 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 = { 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}'; diff --git a/packages/myst-to-typst/src/index.ts b/packages/myst-to-typst/src/index.ts index b7f675081..2883b804d 100644 --- a/packages/myst-to-typst/src/index.ts +++ b/packages/myst-to-typst/src/index.ts @@ -145,7 +145,7 @@ const handlers: Record = { 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 = { 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 += '`'; From e3bc9796093906b2084d05be57ad82a2ff7432d3 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Jan 2025 15:42:39 -0700 Subject: [PATCH 5/5] changeset --- .changeset/gorgeous-trainers-fetch.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .changeset/gorgeous-trainers-fetch.md diff --git a/.changeset/gorgeous-trainers-fetch.md b/.changeset/gorgeous-trainers-fetch.md new file mode 100644 index 000000000..0f730a12a --- /dev/null +++ b/.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.