Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

closes #1776 to make tag/tags in markdown work with jupytext #1780

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

closes #1776 to make tag/tags in markdown work with jupytext #1780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/execute-notebooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Here's an example of adding this tag with a {myst:directive}`code-cell` directiv

````markdown
```{code-cell}
:tags: raises-exception
:tag: raises-exception
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work in jupytext?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think jupytext uses tags, rather than tag. Though it does use square brackets for multiple tags.

https://jupytext.readthedocs.io/en/latest/formats-markdown.html

My feeling is that we should define the syntax we want for MyST, and then upstream the improvements to jupytext to make it work, rather than the other way around

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked by running examples that "tag" works for a single string while "tags" requires brackets in jupytext.

I think it's important to keep documentation in sync with reality as much as possible. I was asked to help, and changing the docs is all I am qualified to do.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we change this all to tags: [raises-exception], that should work in both myst and jupytext correct?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that works.

Copy link
Contributor

@agoose77 agoose77 Jan 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More broadly, options should be parsed as YAML if we're inheriting the spec from myst-parser / myst-nb, etc. I'm broadly in favour of this, because we already use YAML in other user-facing places, and it's a well-known standard to point to.

So, even if we don't actually use yaml.load, I'd like us to use the same standard. Therefore, we should treat tags: "" as something that we upgrade and deprecate.

As for tag -- it's not something we supported in myst-nb, so it's really just a question of whether we want more configuration or not. I'm tempted to not support it yet, because we don't have to.


print("Hello" + 10001)
```
Expand All @@ -57,7 +57,7 @@ For [Markdown notebooks using the {myst:directive}`code-cell` directive](noteboo

````markdown
```{code-cell}
:tags: skip-execution
:tag: skip-execution

name = input("What is your name?")
```
Expand Down
13 changes: 12 additions & 1 deletion docs/notebook-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,22 @@ In Markdown of a jupyter notebook these look like:

````markdown
```{code-cell} python
:tags: remove-input
:tag: remove-input
print("This will show output with no input!")
```
````

for a single tag, or

````markdown
```{code-cell} python
:tags: [my-tag1, my-tag2]
print("This will show output with no input!")
```
````

for any number of tags.

:::{table} Notebook cell tags with special meanings
:label: tbl:notebook-cell-tags

Expand Down
10 changes: 5 additions & 5 deletions docs/notebooks-with-markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,22 +116,22 @@ For example, the following code defines a `remove-input` tag (See all [notebook

````markdown
```{code-cell} python
:tags: remove-input
:tag: remove-input
print("This will show output with no input!")
```
````

and results in the following:

> ```{code-cell} python
> :tags: remove-input
> :tag: remove-input
> print("This will show output with no input!")
> ```

This can be particularly helpful for showing the output of a calculation or plot, which is reproducible in the {download}`source code <./notebooks-with-markdown.md>`, but not shown to the user like this `matplotlib` plot:

```{code-cell} python
:tags: remove-input
:tag: remove-input
# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)
Expand All @@ -149,12 +149,12 @@ plt.show()

For **multiple tags** you have two ways to provide them:

- If you specify argument options with `:`, tags will be parsed as a comma-separated string.
- If you specify argument options with `:`, tags will be parsed as a comma-separated list of strings.
For example:

````markdown
```{code-cell} python
:tags: tag1, tag2,tag3
:tags: [tag1, tag2,tag3]
# Note that whitespace is removed from tags!
print("howdy!")
```
Expand Down