Change Log#
v1.1.2 - 2024-09-24#
Bugs fixed#
Fix incorrect output from prints originating from different processes #604 (@basnijholt)
Maintenance and upkeep improvements#
Documentation improvements#
Update glueing docs for NumPy >=2.0 #615 (@bryanwweber)
Other merged PRs#
build(deps): bump codecov/codecov-action from 3.1.4 to 4.5.0 in the actions group #630 (@dependabot)
Contributors to this release#
(GitHub contributors page for this release)
@agoose77 | @basnijholt | @bryanwweber | @bsipocz | @choldgraf | @chrisjsewell | @dependabot | @LecrisUT | @OriolAbril | @tupui | @welcome
v1.1.1 - 2024-06-27#
Bugs fixed#
FIX: output metadata overwrites image size for all following images #609 (@aeisenbarth)
Maintenance and upkeep improvements#
Documentation improvements#
DOCS: set printoptions to disable modern scalar printing #613 (@agoose77)
DOCS: extra comma forgotten #606 (@jeertmans)
DOCS: update shown code to match source #598 (@OriolAbril)
Contributors to this release#
(GitHub contributors page for this release)
@aeisenbarth | @agoose77 | @jeertmans | @OriolAbril | @sstroemer | @welcome
v1.1.0 - 2024-04-12#
Enhancements made#
ENH: pass-through image metadata #588 (@flying-sheep)
Maintenance and upkeep improvements#
Other merged PRs#
build(deps): bump actions/setup-python from 4 to 5 #576 (@dependabot)
Contributors to this release#
(GitHub contributors page for this release)
@agoose77 | @cisaacstern | @dependabot | @flying-sheep | @ma-sadeghi | @peytondmurray | @PhilipVinc | @sphuber | @welcome
v1.0.0 - 2023-11-08#
New features added#
Bugs fixed#
Maintenance and upkeep improvements#
Documentation improvements#
DOCS: Fix broken pytest fixture #546 (@peytondmurray)
📚 DOCS: Fix typos and add codespell pre-commit hook #475 (@kianmeng)
API and Breaking Changes#
Other merged PRs#
[pre-commit.ci] pre-commit autoupdate #564 (@pre-commit-ci)
[pre-commit.ci] pre-commit autoupdate #561 (@pre-commit-ci)
[pre-commit.ci] pre-commit autoupdate #556 (@pre-commit-ci)
Update readthedocs Config File to fix Test Error #554 (@michaelweinold)
[pre-commit.ci] pre-commit autoupdate #553 (@pre-commit-ci)
build(deps): update ipython requirement from <=8.16.0 to <=8.16.1 #550 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #549 (@pre-commit-ci)
build(deps): update ipython requirement from !=8.1.0,<8.16 to !=8.1.0,<8.17 #548 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #542 (@pre-commit-ci)
build(deps): bump actions/checkout from 3 to 4 #539 (@dependabot)
build(deps): update ipython requirement from !=8.1.0,<8.15 to !=8.1.0,<8.16 #538 (@dependabot)
Update copyright year to 2023 #537 (@GlobalMin)
build(deps-dev): update jupytext requirement from <1.15.0,>=1.11.2 to >=1.11.2,<1.16.0 #534 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #529 (@pre-commit-ci)
build(deps-dev): update coconut requirement from <2.3.0,>=1.4.3 to >=1.4.3,<3.1.0 #527 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #526 (@pre-commit-ci)
Update ipython requirement from !=8.1.0,<8.5 to !=8.1.0,<8.15 #521 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #518 (@pre-commit-ci)
Update coconut requirement from <2.3.0,>=1.4.3 to >=1.4.3,<3.1.0 #517 (@dependabot)
[pre-commit.ci] pre-commit autoupdate #515 (@pre-commit-ci)
Update ipykernel requirement from ~=5.5 to >=5.5,<7.0 #512 (@dependabot)
Update sphinx-book-theme requirement from ~=0.3.0 to >=0.3,<1.1 #510 (@dependabot)
Update jupytext requirement from ~=1.11.2 to >=1.11.2,<1.15.0 #509 (@dependabot)
Contributors to this release#
(GitHub contributors page for this release)
@agoose77 | @aleivag | @choldgraf | @chrisjsewell | @cisaacstern | @codecov | @dependabot | @GlobalMin | @je-cook | @joeldodson | @kianmeng | @kloczek | @LecrisUT | @michaelweinold | @mmcky | @paugier | @peytondmurray | @PhilipVinc | @pre-commit-ci | @rowanc1 | @sphuber | @tupui | @WarrenWeckesser | @welcome | @Yoshanuikabundi
v0.17.2 - 2023-04-21#
This is primarily a maintenance release to support newer versions of dependencies and fix a few bugs.
Maintenance and upkeep improvements#
MAINT: Create dependabot.yml #499 (@choldgraf)
MAINT: Fix codecov jobs and update pre-commit #460 (@choldgraf)
UPDATE: jupyter-cache v0.6.0 #498 (@choldgraf)
Documentation improvements#
DOCS: Hint to avoid Extension error in sphinx-build #494 (@kolibril13, @choldgraf)
DOCS: fix link to gallery #483 (@michaelaye, @choldgraf, @agoose77)
Add note about how to use cell tags #490 (@kolibril13, @choldgraf)
Update quickstart.md to include docs folder #489 (@kolibril13, @choldgraf)
docs: update to latest
sphinx-design
#486 (@agoose77, @choldgraf)
Bug fixes#
fix: use jsdelivr CDN for ipywidgets #491 (@agoose77, @choldgraf)
Add ipywidgets javascript #469 (@OriolAbril, @agoose77)
Contributors to this release#
The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.
(GitHub contributors page for this release)
@agoose77 (activity) | @choldgraf (activity) | @chrisjsewell (activity) | @dependabot (activity) | @kolibril13 (activity) | @michaelaye (activity) | @OriolAbril (activity) | @pre-commit-ci (activity)
v0.17.1 - 2022-30-09#
👌 IMPROVE:
hide-output
button (#450) This now uses the same margin color as the cell source and, when the cell source is present, is “connected” to that, to form a single element. See Hide cell contents for more information.
v0.17.0 - 2022-29-09#
👌 IMPROVE: Replace sphinx-togglebutton with built-in functionality (#446) This allows for tighter integration with myst-nb:
Nicer rendering of the hidden content buttons
Customisation of the hide/show prompts
See Hide cell contents for more information.
🐛 FIX: Inline exec variables with multiple outputs (#440) Previously, it was assumed that a variable evaluation would only ever create 0 or 1 outputs. Multiple are now allowed.
👌 IMPROVE: cache bust changes to CSS (#447)
👌 IMPROVE: Move CSS colors to variables (#448)
v0.16.0 - 2022-06-13#
v0.15.0 - 2022-05-05#
✨ NEW: Add inline
execution mode and eval
role/directive, for inserting code variables directly into the text flow of your documentation!
See Inline variable evaluation for more information.
v0.14.0 - 2022-04-27#
This release encompasses a major rewrite of the entire library and its documentation, primarily in #380 and #405.
Breaking Changes ‼️#
Configuration#
A number of configuration option names have been changed, such that they now share the nb_
prefix.
Most of the deprecated names will be auto-converted at the start of the build, emitting a warning such as:
WARNING: 'jupyter_execute_notebooks' is deprecated for 'nb_execution_mode' [mystnb.config]
nb_render_priority
has been removed and replaced by nb_mime_priority_overrides
, which has a different format and is more flexible. See Outputs MIME priority for more information.
As per the changes in myst_parser
, the dollarmath
syntax extension is no longer included by default.
To re-add this extension, ensure that it is specified in your conf.py
: myst_enable_extensions = ["dollarmath"]
.
For cell-level configuration the top-level key render
has now been deprecated for mystnb
.
For example, replace:
```{code-cell}
---
render:
image:
width: 200px
---
...
```
with:
```{code-cell}
---
mystnb:
image:
width: 200px
---
...
```
render
will currently still be read, if present, and will issue a [mystnb.cell_metadata_key]
warning.
The jupyter_sphinx_require_url
and jupyter_sphinx_embed_url
configuration options are no longer used by this package, and are replaced by nb_ipywidgets_js
.
See the configuration section for more details.
Dependencies#
The ipywidgets package has been removed from the requirements. If required, please install it specifically.
AST structure and rendering plugins#
The structure of the docutils AST and nodes produced by MyST-NB has been fully changed, for compatibility with the new docutils only functionality. See the API documentation for more details.
The renderer plugin system (used by the myst_nb.renderers
entry point) has also been completely rewritten,
so any current existing renderers will no longer work.
There is also now a new myst_nb.mime_renderers
entry point, to allow for targeted rendering of specific code-cell output MIME types.
See Customise the render process for more information.
Glue functionality#
By default, glue
roles and directives now only work for keys within the same document.
To reference glued content in a different document, the glue:any
directive allows for a doc
option and glue:any
/glue:text
roles allow the (relative) doc path to be added, for example:
```{glue:any} var_text
:doc: other.ipynb
```
{glue:text}`other.ipynb::var_float:.2E`
This cross-document functionality is currently restricted to only text/plain
and text/html
output MIME types, not images.
See Embedding outputs as variables for more details.
Dependency changes ⬆️#
Removed:
ipywidgets
jupyter_sphinx
nbconvert
Updated:
Python
:3.6+ -> 3.7+
myst_parser
:0.15 -> 0.17
jupyter-cache
:0.4 -> 0.5
sphinx-togglebutton
:0.1 -> 0.3
New and improved ✨#
The following is a non-exhaustive list of new features and improvements, see the rest of the documentation for all the changes.
Multi-level configuration (global (
conf.py
) < notebook level metadata < cell level metadata)Plus new config options including:
nb_number_source_lines
,nb_remove_code_source
,nb_remove_code_outputs
,nb_render_error_lexer
,nb_execution_raise_on_error
,nb_kernel_rgx_aliases
See the configuration section for more details.
Added
mystnb-quickstart
andmystnb-to-jupyter
CLI commands.MyST text-based notebooks can now be specified by just:
--- file_format: mystnb kernelspec: name: python3 ---
as opposed to the alternative jupytext top-matter. See Text-based Notebooks for more details.
docutils API/CLI with command line tools, e.g.
mystnb-docutils-html
Includes
glue
roles and directivesSee single page builds for more details.
Parallel friendly (e.g.
sphinx-build -j 4
can execute four notebooks in parallel)Page specific loading of ipywidgets JavaScript, i.e. only when ipywidgets are present in the notebook.
Added raw cell rendering, with the
raw-cell
directive. See Raw cells authoring for more details.Added MIME render plugins. See Customise the render process for more details.
Better log info/warnings, with
type.subtype
specifiers for warning suppression. See Warning suppression for more details.Reworked jupyter-cache integration to be easier to use (including parallel execution)
Added image options to
glue:figure
New
glue:md
role/directive includes nested parsing of MyST Markdown. See Embedding outputs as variables for more details.Improved
nb-exec-table
directive (includes links to documents, etc)
Additional Pull Requests#
v0.13.2 - 2022-02-10#
This release improves for cell outputs and brings UI improvements for toggling cell inputs and outputs. It also includes several bugfixes.
Use configured
nb_render_plugin
for glue nodes #337 (@bryanwweber)UPGRADE: sphinx-togglebutton v0.3.0 #390 (@choldgraf)
0.13.1 - 2021-10-04#
✨ NEW: nb_merge_streams
configuration [PR #364]
If nb_merge_streams=True
, all stdout / stderr output streams are merged into single outputs. This ensures deterministic outputs.
0.13.0 - 2021-09-02#
Upgraded to sphinx
v4 ⬆️#
The primary change in this release is to update the requirements of myst-nb from sphinx>=2,<4
to sphinx>=3,<5
to
support sphinx>=4
[PR #356].
👌 IMPROVE: Allows more complex suffixes in notebooks [PR #328]
⬆️ UPDATE: myst-parser to
0.15.2
[PR #353]⬆️ UPGRADE: nbconvert 6 support [PR #326]
⬆️ UPGRADE: markdown-it-py v1.0 [PR #320]
🔧 MAINT: Pin ipykernel to ~v5.5 [PR #347]
🔧 MAINT: Make a more specific selector for no-border [PR #344]
Many thanks to @akhmerov, @bollwyvl, @choldgraf, @chrisjsewell, @juhuebner, @mmcky
0.12.1 - 2021-04-25#
⬆️ UPDATE: jupyter_sphinx to
0.3.2
: fixesNotebook code has no file extension metadata
warning)⬆️ UPDATE: importlib_metadata to
3.6
: to use new entry point loading interfaceOfficial support for Python 3.9
(0.12.2
and 0.12.3
fix a regression, when working with the entry point loading interface)
0.12.0 - 2021-02-23#
This release adds an experimental MyST-NB feature to enable loading of code from a file
for code-cell
directives using a :load: <file>
option.
Usage information is available in the docs
0.11.1 - 2021-01-20#
Minor update to handle MyST-Parser v0.13.3
and v4.5
notebooks.
0.11.0 - 2021-01-12#
This release updates MyST-Parser to v0.13
,
which is detailed in the myst-parser changelog.
The primary change is to the extension system, with extensions now all loaded via myst_enable_extensions = ["dollarmath", ...]
,
and a number of extensions added or improved.
0.10.2 - 2021-01-12#
Minor fixes:
🐛 FIX: empty myst file read
🐛 FIX: remove cell background-color CSS for cells
🔧 MAINTAIN: Pin jupyter-sphinx version
0.10.1 - 2020-09-08#
- ⬆️ UPGRADE: myst-parser v0.12.9
Minor bug fixes and enhancements / new features
0.10.0 - 2020-08-28#
- ⬆️ UPGRADE: jupyter-sphinx v0.3, jupyter-cache v0.4.1 and nbclient v0.5.
These upgrades allow for full Windows OS compatibility, and improve the stability of notebook execution on small machines.
👌 IMPROVE: Formatting of stderr is now similar to stdout, but with a slight red background.
🧪 TESTS: Add Windows CI
0.9.2 - 2020-08-27#
- ⬆️ UPGRADE: myst-parser patch version
to ensure a few new features and bug fixes are incorporated (see its CHANGELOG.md)
0.9.1 - 2020-08-24#
More configuration!
✨ NEW: Add stderr global configuration:
nb_output_stderr
(see removing stderr)✨ NEW: Add
nb_render_key
configuration (see formatting outputs)🐛 FIX:
auto
execution not recognising (and skipping) notebooks with existing outputs
0.9.0 - 2020-08-24#
This versions see’s many great changes; utilising the ⬆️ upgrade to myst-parser=v0.12
and accompanying ⬆️ upgrade to sphinx=v3
,
as well as major refactors to the execution (#236) and code output rendering (#243).
Plus much more configuration options, to allow for a more configurable workflow (the defaults work great as well!).
Below is a summary of the changes, and you can also check out many examples in the documentation, https://myst-nb.readthedocs.io/, and the MyST-Parser Changelog for all the new Markdown parsing features available: executablebooks/MyST-Parser.
New ✨#
Custom notebook formats:
Configuration and logic has been added for designating additional file types to be converted to Notebooks, which are then executed & parsed in the same manner as regular Notebooks. See Custom Notebook Formats for details.
Allow for configuration of render priority (per output format) with
nb_render_priority
.The code cell output renderer class is now loaded from an entry-point, with a configurable name, meaning that anyone can provide their own renderer subclass. See Customise the render process for details.
Assignment of metadata tags
remove-stdout
andremove-stderr
for removal of the relevant outputs (see here)Render
text/markdown
MIME types with an integrated CommonMark parser (see here).Add code output image formatting, via cell metadata, including size, captions and labelling (see here).
Notebook outputs ANSI lexer which is applied to stdout/stderr and text/plain outputs, and is configurable via
nb_render_text_lexer
(see here).Capture execution data in sphinx env, which can be output into the documentation, with the
nb-exec-table
directive. See Execution statistics for details.
Improved 👌#
Standardise auto/cache execution
Both now call the same underlying function (from
jupyter-cache
) and act the same. This improvesauto
, by making it output error reports and not raising an exception on an error. Additional config has also been added:execution_allow_errors
andexecution_in_temp
. As for fortimeout
,allow_errors
can also be set in the notebookmetadata.execution.allow_errors
This presents one breaking change, in thatcache
will now by default execute in a the local folder as the CWD (not a temporary one).
Fixed 🐛#
Code cell source code is now assigned the correct lexer when using custom kernels (39c1bb9)
Documented 📚#
Add example of using kernels other than Python (676eb2c)
Refactored ♻️#
Add more signature typing and docstrings
Move config value validation to separate function
Rename functions in cache.py and improve their logical flow
Rename variable stored in sphinx environment, to share same suffix:
path_to_cache
->nb_path_to_cache
allowed_nb_exec_suffixes
->nb_allowed_exec_suffixes
excluded_nb_exec_paths
->nb_excluded_exec_paths
Initial Nb output rendering:
Ensure source (path, lineno) are correctly propagated to
CellOutputBundleNode
Capture cell level metadata in
CellOutputBundleNode
New
CellOutputRenderer
class to contain render methodsSimplify test code, using sphinx
get_doctree
andget_and_resolve_doctree
methods
0.8.5 - 2020-08-11#
Improved 👌#
Add configuration for traceback in stderr (#218)
Fixed 🐛#
MIME render priority lookup
Upgrades ⬆️#
myst-parser -> 0.9
jupyter-cache to v0.3.0
Documented 📚#
More explanation of myst notebooks (#213)
Update contributing guide
Contributors for previously releases#
Thanks to all these contributors 🙏:
@AakashGfude | @akhmerov | @amueller | @choldgraf | @chrisjsewell | @codecov | @consideRatio | @jstac | @matthew-brett | @mmcky | @phaustin | @rossbar | @rowanc1 | @seanpue | @stefanv | @TomDonoghue | @tonyfast | @welcome