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
```
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. :)