python-sphinxmyst

MyST sphinx extension does not recognize `{code-cell}` directive


I am struggling to get the myst_parser sphinx extension to recognize the {code-cell} directive. Sphinx issues this warning:

/home/dallan/Repos/bnl/myst_test/docs/index.md.rst:3: WARNING: Unknown directive type: 'code-cell' [myst.directive_unknown]

I think I must be missing something obvious. Here is a minimal example.

tree docs
docs
├── conf.py
└── index.md

0 directories, 2 files
$ cat docs/conf.py 
extensions=["myst_parser"]
$ cat docs/index.md 
# Test

```{admonition} Here's my title
:class: warning

Here's my admonition content
```

```{code-cell} ipython3
1 + 1
```
$ sphinx-build docs docs/html
Running Sphinx v8.0.2
loading translations [en]... done
making output directory... done
myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
/home/dallan/Repos/bnl/myst_test/docs/index.md.rst:3: WARNING: Unknown directive type: 'code-cell' [myst.directive_unknown]
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in docs/html.

Note the warning: Unknown directive type: 'code-cell' [myst.directive_unknown]. Notably, the {admonition} directive works and renders as expected in HTML; only the {code-cell} directive fails.

The above was run in a clean environment with sphinx and myst_parser installed from PyPI:

$ pip list
Package                       Version
----------------------------- --------
alabaster                     1.0.0
babel                         2.16.0
certifi                       2024.7.4
charset-normalizer            3.3.2
docutils                      0.21.2
idna                          3.8
imagesize                     1.4.1
Jinja2                        3.1.4
markdown-it-py                3.0.0
MarkupSafe                    2.1.5
mdit-py-plugins               0.4.1
mdurl                         0.1.2
myst-parser                   4.0.0
packaging                     24.1
pip                           24.2
Pygments                      2.18.0
PyYAML                        6.0.2
requests                      2.32.3
setuptools                    72.2.0
snowballstemmer               2.2.0
Sphinx                        8.0.2
sphinxcontrib-applehelp       2.0.0
sphinxcontrib-devhelp         2.0.0
sphinxcontrib-htmlhelp        2.1.0
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          2.0.0
sphinxcontrib-serializinghtml 2.0.0
urllib3                       2.2.2
wheel                         0.44.0

I suspect this is a "Problem Exists Between Chair and Keyboard" situation---any help appreciated!

References:


Update: Reading Execute Notebooks During Your Build I saw

In order to execute your MyST content, you must install a Jupyter Server and the kernel needed to execute your code (e.g., the IPython kernel, the Xeus Python kernel, or the IRKernel.)

I added ipykernel and jupyter-server to my environment, but it did not change the outcome. I am still missing something.


Update #2: A header is required to support code execution; I have updated my minimal example thus:

$ cat docs/index.md 
---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.16.4
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---
# Test

```{admonition} Here's my title
:class: warning

Here's my admonition content
```

```{code-cell} ipython3
1 + 1
```

Solution

  • The code-cell directive is added by a sibling extension mystnb. If you have mystnb enabled in your Sphinx application, you don't need to manually configure (and shouldn't!) myst-parser. :)