diff --git a/.changeset/dirty-ducks-tie.md b/.changeset/dirty-ducks-tie.md new file mode 100644 index 000000000..aff2128d8 --- /dev/null +++ b/.changeset/dirty-ducks-tie.md @@ -0,0 +1,6 @@ +--- +"myst-frontmatter": patch +"myst-cli": patch +--- + +Add support for skipping execution of individual notebooks diff --git a/docs/execute-notebooks.md b/docs/execute-notebooks.md index 291c310b6..788bd8a72 100644 --- a/docs/execute-notebooks.md +++ b/docs/execute-notebooks.md @@ -65,6 +65,24 @@ name = input("What is your name?") Additional [cell tags](#tbl:notebook-cell-tags) to hide, remove, or raise exceptions are also possible. +## Skip entire notebooks + +You may wish to disable execution for certain notebooks. This can be done by setting the top-level `skip_execution` frontmatter option to `true`, e.g. + +````markdown +--- +kernelspec: + name: python3 + display_name: Python 3 + +skip_execution: true +--- + +```{code-cell} +print("This will never be executed!") +``` +```` + ## Cache execution outputs When MyST executes your notebook, it will store the outputs in a cache in a folder called `execute/` in your MyST build folder. diff --git a/docs/frontmatter.md b/docs/frontmatter.md index 376336e49..b6d00bc8d 100644 --- a/docs/frontmatter.md +++ b/docs/frontmatter.md @@ -229,6 +229,9 @@ The following table lists the available frontmatter fields, a brief description * - `kernelspec` - configuration for the kernel (see [](#kernel-specification)) - page only +* - `skip_execution` + - opt-out of execution for a particular document (see [](./execute-notebooks)) + - page only ``` +++ @@ -850,4 +853,4 @@ These fields provide a more complete superset of publication metadata than the [ > Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover." -If MyST frontmatter includes an OpenAlex `biblio` object, it will be coerced to valid publication metadata. \ No newline at end of file +If MyST frontmatter includes an OpenAlex `biblio` object, it will be coerced to valid publication metadata. diff --git a/packages/myst-cli/src/process/mdast.ts b/packages/myst-cli/src/process/mdast.ts index 39acbdf2a..39093be02 100644 --- a/packages/myst-cli/src/process/mdast.ts +++ b/packages/myst-cli/src/process/mdast.ts @@ -219,7 +219,7 @@ export async function transformMdast( // Combine file-specific citation renderers with project renderers from bib files const fileCitationRenderer = combineCitationRenderers(cache, ...rendererFiles); - if (execute) { + if (execute && !frontmatter.skip_execution) { const cachePath = path.join(session.buildPath(), 'execute'); await kernelExecutionTransform(mdast, vfile, { basePath: session.sourcePath(), diff --git a/packages/myst-frontmatter/src/page/types.ts b/packages/myst-frontmatter/src/page/types.ts index f738f79ef..34ed4bfdc 100644 --- a/packages/myst-frontmatter/src/page/types.ts +++ b/packages/myst-frontmatter/src/page/types.ts @@ -13,6 +13,7 @@ export const PAGE_FRONTMATTER_KEYS = [ 'site', 'enumerator', 'content_includes_title', + 'skip_execution', ]; export type PageFrontmatter = ProjectAndPageFrontmatter & { @@ -21,6 +22,8 @@ export type PageFrontmatter = ProjectAndPageFrontmatter & { jupytext?: Jupytext; tags?: string[]; enumerator?: string; + // Disable execution for this page + skip_execution?: boolean; /** Flag if frontmatter title is duplicated in content * * Set during initial file/frontmatter load diff --git a/packages/myst-frontmatter/src/page/validators.ts b/packages/myst-frontmatter/src/page/validators.ts index a7552eae1..6018ba861 100644 --- a/packages/myst-frontmatter/src/page/validators.ts +++ b/packages/myst-frontmatter/src/page/validators.ts @@ -51,6 +51,12 @@ export function validatePageFrontmatterKeys(value: Record, opts: Va if (defined(value.jupytext)) { output.jupytext = validateJupytext(value.jupytext, incrementOptions('jupytext', opts)); } + if (defined(value.skip_execution)) { + output.skip_execution = validateBoolean( + value.skip_execution, + incrementOptions('skip_execution', opts), + ); + } if (defined(value.enumerator)) { output.enumerator = validateString(value.enumerator, incrementOptions('enumerator', opts)); }