Allow putting {code-cell} within {only} directive.

[schmoelder]

Describe the bug

When I add the following to a chapter

````{only} html
```{code-cell} ipython3
print('Using html/backticks')
```
````

or

:::{only} html
```{code-cell} ipython3
print('Using html/colon')
```
:::

I would like this cell (and its output) only to be visible in html output (or latex output).

However, the page is simply empty.

The same happens if I specify latex

Reproduce the bug

To reproduce, I created a new book using

jupyter-book create mynewbook/

and added a new chapter with the following content.

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.11.5
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Test if `only` directive works.

## Only print stuff

Seems to work...

```{only} html
This should only be visibile in `html` output.
Using html/backticks
```

:::{only} html
This should only be visible in `html` output.
Using html/colons
:::

```{only} latex
This should only be visibile in `latex` output.
Using latex/backticks
```

:::{only} latex
This should only be visible in `latex` output.
Using latex/colon
:::

## Evaluate Stuff

Does not seem to work...

````{only} html
```{code-cell} ipython3
print('Using html/backticks')
```
````

:::{only} html
```{code-cell} ipython3
print('Using html/colon')
```
:::

````{only} latex
```{code-cell} ipython3
print('Using latex/backticks')
```
````

:::{only} latex
```{code-cell} ipython3
print('Using latex/colon')
```
:::

List your environment

> jupyter-book --version

Jupyter Book      : 0.15.0
External ToC      : 0.3.1
MyST-Parser       : 0.18.1
MyST-NB           : 0.17.1
Sphinx Book Theme : 1.0.0
Jupyter-Cache     : 0.5.0
NbClient          : 0.5.13

[schmoelder]

Oh, and I did get the following error

/home/jo/code/mynewbook/demo.md:59: WARNING: Found an unexpected `code-cell` or `raw-cell` directive. Either this file was not converted to a notebook, because Jupytext header content was missing, or the `code-cell` was not converted, because it is nested. See https://myst-nb.readthedocs.io/en/latest/use/markdown.html for more information. [mystnb.nbcell]

Just wanted to add that the link seems to be broken. I assume it's supposed to lead me to https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives However, it does not explicitly state that nesting code-cells does not work...

[agoose77]

As you note, that page no longer exists in our documentation. I think we can potentially improve that by ensuring any code-generated URLs to our documentation are versioned by release, which would ensure that they work.

The original code-cell documentation makes an implicit reference to the fact that they can't be nested:

The content inside {code-cell} makes up the content of the cell, and will be executed at build time.

But it could be clearer still!

As for the use of only, that's an interesting idea. From looking at the implementation of only, it operates as a post transform, whilst myst-nb operates as a source parser. My hunch is therefore that we would need to add special only support to myst-nb if we wanted this to work. @chrisjsewell is my understanding correct here?

[schmoelder]

Thanks for your feedback! Ok, I did not understand that reference...

Maybe to give some context, I have a code-cell that produces a lot of output. I don't mind that for the html build since I can add a scroll-output tag. But for TeX, this needs to be hidden. Do you have any suggestion how to achieve this?

[agoose77]

My strategy for my thesis (when I knew less of Sphinx) was to create a simple extension.

With this config

sphinx:
  recursive_update: true
  local_extensions:
    # Hide any :dropdown: or {toggle} content for LaTeX
    hide_builder_classes: ./sphinx-ext
  config:
    builder_ignore_classes:
        latex:
            - dropdown
            - toggle
            - margin
            - tag_no-latex

The LaTeX builder hides dropdowns, toggles, margins, and also any cells with a tag of no-latex. This means that you can add no-latex tags to the cells that should not be shown.

If you wanted to hide only the output (and keep the source), I think you'd need to be more specific in the extension, e.g. look for cell output nodes explicitly.

There may be other ways to do this, but this was my starting point!

[uqtmiller]

@agoose77 I just want to thank you for sharing this incredibly helpful resource, which worked straight out of the box and solved my problem exactly. This is just perfect. Brilliant stuff!

[agoose77]

Thanks for the feedback @uqtmiller! In the world of open source, it's nice to see your own impact!

I took this as a cue to formally release a package on PyPI that you can pip install. It uses different names for the configuration values than the example above, but it should be clear from the documentation.

[uqtmiller]

Great idea, @agoose77! Excellent work.

Thanks again!

[tuncbkose]

I'd like to be able to specify some builder-specific setup in a {code-cell} embedded in {only} at the start of my document so that the rest outputs differently based on whether I'm building PDF or HTML. So implementing something like

My hunch is therefore that we would need to add special only support to myst-nb if we wanted this to work.

would be great.