UPGRADE: myst-nb and many other dependencies

.github/workflows/tests.yml

@@ -87,7 +87,7 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.7", "3.8", "3.9"]
-        sphinx: [">=4,<5"]
+        sphinx: [">=4,<5", ">=5,<6"]
 
     steps:
     - uses: actions/checkout@v3
@@ -100,8 +100,8 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install wheel
-        pip install "sphinx${{ matrix.sphinx }}"
         pip install -e .[testing]
+        pip install "sphinx${{ matrix.sphinx }}"
 
     - name: Install Headless Chrome dependencies
       run: |

CHANGELOG.md

@@ -339,7 +339,7 @@ This release includes a number of new features, improvements and bug fixes. Ther
 * 👌 IMPROVE: Option to exclude every file not in the toc. ([docs](docs/customize/config.md), [#1123](https://github.com/executablebooks/jupyter-book/pull/1123), [@alex-treebeard](https://github.com/alex-treebeard))
 *  ✨ NEW: Enable the use of local Sphinx extension via _config.yml. ([docs](docs/customize/config.md), [#1102](https://github.com/executablebooks/jupyter-book/pull/1102), [@mmcky](https://github.com/mmcky))
 * ✨ NEW: Enable custom builder passthrough. This is an **advanced feature**
-  that enables the use of additional sphinx builders via jupyter-book that may be provided by an extension. ([docs](docs/advanced/sphinx.md), [#1094]([#1094](https://github.com/executablebooks/jupyter-book/pull/1094)), [@mmcky](https://github.com/mmcky))
+  that enables the use of additional sphinx builders via jupyter-book that may be provided by an extension. ([docs](docs/advanced/sphinx.md), [#1094](https://github.com/executablebooks/jupyter-book/pull/1094), [@mmcky](https://github.com/mmcky))
 
 **HTML:**
 

docs/_config.yml

@@ -15,6 +15,9 @@ bibtex_bibfiles:
 
 execute:
   execute_notebooks: cache
+  stderr_output: "remove"
+  allow_errors: true
+  timeout: 120
 
 html:
   announcement: "⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️"
@@ -25,6 +28,8 @@ html:
   use_repository_button: true
   use_issues_button: true
   baseurl: https://jupyterbook.org/
+  analytics:
+    google_analytics_id = ''
 
 repository:
   url: https://github.com/executablebooks/jupyter-book
@@ -60,9 +65,13 @@ latex:
 sphinx:
   config:
     bibtex_reference_style: author_year  # or label, super, \supercite
+    # unknown_mime_type - application/vnd.plotly.v1+json and application/vnd.bokehjs_load.v0+json
+    # domains - sphinx_proof.domain::prf needs to have `resolve_any_xref` method
+    # mime_priority - latex priority not set in myst_nb for text/html, application/javascript
+    suppress_warnings: ["mystnb.unknown_mime_type", "myst.domains", "mystnb.mime_priority"]
     copybutton_prompt_text: "$"
-    execution_show_tb: True
-    execution_timeout: 120
+    nb_execution_show_tb: True
+    nb_execution_timeout: 120
     html_extra_path:
       - images/badge.svg
     intersphinx_mapping:
@@ -114,6 +123,7 @@ sphinx:
       content-types/jupytext.md: file-types/jupytext.Rmd
       content-types/restructuredtext.md: file-types/restructuredtext.md
       customize/toc.md: structure/toc.md
+    sd_fontawesome_latex: True
 
 
   extra_extensions:

docs/_toc.yml

@@ -96,5 +96,6 @@ parts:
     title: Gallery of Jupyter Books
   - file: explain/components
   - file: cite
+  - file: explain/migration
   - file: reference/_changelog
     title: Change log

docs/content/code-outputs.md

@@ -93,6 +93,18 @@ for ii in range(40):
     print(f"this is output line {ii}")
 ```
 
+When writing MyST markdown documents you may use `:tags: ["output_scroll"]` as an option
+to the `code-cell` directive such as:
+
+````
+```{code-cell} ipython3
+:tags: [output_scroll]
+
+for ii in range(40):
+    print(f"this is output line {ii}")
+```
+````
+
 (content:code-outputs:images)=
 ## Images
 
@@ -115,7 +127,7 @@ We can also set a caption (which is rendered as [CommonMark](https://commonmark.
 ````md
 ```{code-cell} ipython3
 ---
-render:
+mystnb:
   image:
     width: 200px
     alt: fun-fish
@@ -134,7 +146,7 @@ produces the following code cell and figure:
 
 ```{code-cell} ipython3
 ---
-render:
+mystnb:
   image:
     width: 300px
     alt: fun-fish
@@ -234,15 +246,16 @@ For example, this is the default priority list for HTML:
 ```yaml
 sphinx:
   config:
-    nb_render_priority:
-      html:
-      - "application/vnd.jupyter.widget-view+json"
-      - "application/javascript"
-      - "text/html"
-      - "image/svg+xml"
-      - "image/png"
-      - "image/jpeg"
-      - "text/markdown"
-      - "text/latex"
-      - "text/plain"
+    nb_mime_priority_overrides: [
+      ['html', 'application/vnd.jupyter.widget-view+json', 10],
+      ['html', 'application/javascript', 20],
+      ['html', 'text/html', 30],
+      ['html', 'image/svg+xml', 40],
+      ['html', 'image/png', 50],
+      ['html', 'image/gif', 60],
+      ['html', 'image/jpeg', 70],
+      ['html', 'text/markdown', 80],
+      ['html', 'text/latex', 90],
+      ['html', 'text/plain', 100]
+    ]
 ```

docs/content/content-blocks.md

@@ -1,18 +1,19 @@
 ---
-substitutions:
-  key1: "I'm a **substitution**"
-  key2: |
-    ```{note}
-    {{ key1 }}
-    ```
-  fishy: |
-    ```{image} /images/fun-fish.png
-    :alt: fishy
-    :width: 200px
-    ```
-  jinja: "[Jinja templates](https://jinja.palletsprojects.com/en/2.11.x/)"
-  repo_name: "jupyter-book"
-  repo_url: "[my repo url](https://github.com/executablebooks/jupyter-book)"
+myst:
+  substitutions:
+    key1: "I'm a **substitution**"
+    key2: |
+      ```{note}
+      {{ key1 }}
+      ```
+    fishy: |
+      ```{image} /images/fun-fish.png
+      :alt: fishy
+      :width: 200px
+      ```
+    jinja: "[Jinja templates](https://jinja.palletsprojects.com/en/2.11.x/)"
+    repo_name: "jupyter-book"
+    repo_url: "[my repo url](https://github.com/executablebooks/jupyter-book)"
 ---
 
 # Special content blocks
@@ -166,7 +167,7 @@ You can use this syntax for any kind of directive, though it is generally recomm
 ### Insert code cell outputs into admonitions
 
 If you'd like to insert the outputs of running code *inside* admonition
-blocks, we recommend using [`glue` functionality](content:code-outputs:glue).
+blocks, we recommend using [`glue` functionality](content:executable:output-insert).
 For example, we'll insert one of the outputs that was glued into the book from the [code outputs page](./code-outputs.md).
 
 For example:
@@ -176,12 +177,13 @@ For example:
 ```{note}
 Here's my figure:
 
-```{glue:figure} sorted_means_fig
+```{glue} sorted_means_fig
+:doc: executable/output-insert.md
 ```
 
 ````
 
-See [](content:code-outputs:glue) for more information on how to use `glue` to insert your outputs directly into your content.
+See [](content:executable:output-insert) for more information on how to use `glue` to insert your outputs directly into your content.
 
 :::{tip}
 To hide code input and output that generated the variable you are inserting, use the `remove_cell` tag.
@@ -470,17 +472,18 @@ To use a substitution, first add front-matter content to the top of a page like
 
 ````yaml
 ---
-substitutions:
-  key1: "I'm a **substitution**"
-  key2: |
-    ```{note}
-    {{ key1 }}
-    ```
-  fishy: |
-    ```{image} img/fun-fish.png
-    :alt: fishy
-    :width: 200px
-    ```
+myst:
+  substitutions:
+    key1: "I'm a **substitution**"
+    key2: |
+      ```{note}
+      {{ key1 }}
+      ```
+    fishy: |
+      ```{image} img/fun-fish.png
+      :alt: fishy
+      :width: 200px
+      ```
 ---
 ````
 
@@ -521,7 +524,7 @@ These substitutions will be available throughout your book. For example, the glo
 
 ### Formatting substitutions
 
-MyST substitutions use {{ jinja }} in order to substite in key / values. This means that you can apply any standard Jinja formatting to your substitutions. For example, you can **replace text in your substitutions** like so:
+MyST substitutions use {{ jinja }} in order to substitute in key / values. This means that you can apply any standard Jinja formatting to your substitutions. For example, you can **replace text in your substitutions** like so:
 
 ```{example}
 The original key1: {{ key1 }}

docs/content/executable/output-insert.md

@@ -9,21 +9,31 @@ kernelspec:
   name: python3
 ---
 
-(content:code-outputs:glue)=
+(content:executable:output-insert)=
 # Store code outputs and insert into content
 
 You often wish to run analyses in one notebook and insert them in your
 documents elsewhere. For example, if you'd like to include a figure,
 or if you want to cite an analysis that you have run.
 
-```{margin}
+```{warning}
 Currently, `glue` only works with Python.
 ```
 
+```{seealso}
+There have been changes in `jupyter-book>=0.14` in the way `glue`
+works. Please [see this page for more details](explain:migration).
+
+One of the major updates is that `glue` references between documents
+now require to use `:doc:`. An example is [available here](explain:migration:glue)
+
+```
+
 The `glue` tool from [MyST-NB](https://myst-nb.readthedocs.io/)
 allows you to add a key to variables in a notebook,
-then display those variables in your book by referencing the key. It
-follows a two-step process:
+then display those variables in your book by referencing the key.
+
+It follows a two-step process:
 
 * **Glue a variable to a name**. Do this by using
   the `myst_nb.glue` function on a variable
@@ -39,8 +49,6 @@ We'll cover each step in more detail below.
 For more information about roles, see [](../myst.md).
 :::
 
-+++
-
 (glue/gluing)=
 ## Gluing variables in your notebook
 
@@ -61,15 +69,13 @@ You can then insert it into your text. Adding
 `` {glue:}`cool_text` `` to your content results in the
 following: {glue:}`cool_text`.
 
-### Gluing numbers, plots, and tables
+### Gluing numbers, plots, math, and tables
 
-You can glue anything in your notebook and display it later with `{glue:}`. Here
+You can glue anything in your notebook (or page) and display it later with `{glue:}`. Here
 we'll show how to glue and paste **numbers and images**. We'll simulate some
 data and run a simple bootstrap on it. We'll hide most of this process below,
 to focus on the glueing part.
 
-+++
-
 ```{code-cell} ipython3
 :tags: [hide-cell]
 

docs/content/execute.md

@@ -36,14 +36,25 @@ execute:
   execute_notebooks: auto
 ```
 
+or equivalently:
+
+```yaml
+sphinx:
+  config:
+    nb_execution_mode: auto
+```
+
+Both of the above configurations are global, for per-file use `execution_mode` key.
+
 This will only execute notebooks that are missing at least one output.
 If the notebook has *all* of its outputs populated, then it will not be executed.
 
 **To force the execution of all notebooks, regardless of their outputs**, change the
 above configuration value to:
 
 ```yaml
-execute_notebooks: force
+execute:
+  execute_notebooks: force
 ```
 
 **To cache execution outputs with [jupyter-cache]**, change the above configuration
@@ -56,6 +67,15 @@ execute:
 
 See {ref}`execute/cache` for more information.
 
+**To execute notebooks inline during parsing**, change the above configuration value to:
+
+```yaml
+execute:
+  execute_notebooks: inline
+```
+
+See [Inline variable evaluation (eval)](https://myst-nb.readthedocs.io/en/latest/render/inline.html#render-eval) for more information.
+
 **To turn off notebook execution**, change the above configuration value to:
 
 ```yaml
@@ -333,7 +353,7 @@ Enable activate execution tracebacks, in your `_config.yml`:
 ```yaml
 sphinx:
   config:
-    execution_show_tb: True
+    nb_execution_show_tb: True
 ```
 
 See [the MyST-NB documentation](https://myst-nb.readthedocs.io) for more information.

docs/content/figures.md

@@ -134,7 +134,7 @@ Here is my figure caption!
 
 :::{note}
 You can also include figures that were generated by your code in notebooks.
-To do so, see [](content:code-outputs:glue).
+To do so, see [](content:executable:output-insert).
 :::
 
 ## Markdown figures

docs/content/references.md

@@ -179,7 +179,7 @@ Then, you may use the `{numref}` role in the same way that you use it for Figure
 
 If you wish to use Markdown style syntax, then MyST Markdown will try to find a reference from any of the above reference types (and more!).
 
-This has an advantage, in that you can used nested markdown syntax in your text, for example:
+This has an advantage, in that you can use nested markdown syntax in your text, for example:
 
 ```{example}
 

docs/contribute/intro.md

@@ -174,7 +174,7 @@ what kinds of functionality they support:
   {term}`the MyST-Parser<MyST-Parser>`.
 * {term}`The MyST-NB package<MyST-NB>` parses Jupyter Notebooks into Sphinx and also
   controls some parts of notebook execution.
-  It also allows [inserting code outputs into content](content:code-outputs:glue).
+  It also allows [inserting code outputs into content](content:executable:output-insert).
 * {term}`Jupyter-Cache` manages the execution and cacheing of notebook content at
   build time. It is controlled by {term}`MyST-NB`.
 * The {term}`Sphinx Book Theme` defines the look and feel of Jupyter Book, and is