⬆️ UPGRADE: sphinx v3, myst-nb v0.10

[chrisjsewell]

• Add tox for sphinx 2/3 tests, and docs builds

• add github CI for sphinx 2/3

• add windows support (Add windows 10 support #575)

• Add new options to _config.yml (including config for turning on all myst-parser extended syntaxes at once?)

• Add more CLI options related to sphinx (nitpick, keep-going, freshenv)

• verbosity CLI option? Question: debug/verbose mode? #585

• document new CLI options

• Document changes from myst-parser CHANGELOG

• Document changes from myst-nb CHANGELOG

• Check for documentation improvements to address issues in https://github.com/orgs/executablebooks/projects/5#card-44324532

  • Warning messages and TimeoutError: Cell execution timed out #613
  • Build fails with Scala kernel notebooks #875
  • Syntax highlighting for non-python kernels in code-cell directive #878
  • Support for ANSI color sequences in Jupyter cell output #762
  • RMarkdown files #745
  • When directing users to add tags to their cells, link to the "how to add tags" FAQ #828
  • Support for Markdown in Jupyter Notebook outputs #754
  • Pass flags/options to sphinx-build #743
  • Provide means to hide stdout and/or stderr #694
  • Remove stderr from outputs #430
  • Document how the execution context is determined. #705
  • Rendering MyST figures in the notebook? #629
  • Figures from notebook outputs with link to img file executablebooks/meta#114
  • Best practices for including local image in notebook executablebooks/meta#111

• Improve error reporting (don't show spurious traceback)

• Improve testing (move from subprocess to click.CliRunner, fixes test suit needs to have jb in $PATH #896)

• Lazy imports for click functions

• Replace admonitions with new style

• Replace nested bullet-lists with definition lists

• add correct myst config to docs

• include/document sphinx-panels Include sphinx-panels in the base jupyter book distribution? #690

• Add warning that Python 3.8 on Windows does not currently support notebook execution (jupyter-book build: NotImplementedError on Windows Python 3.8 #906)

• add nbclient to versions reported in jb --version

• Add note about sphinx extensions for images (Docs should specify which image types are supported #918)

• add redirect for content-type -> file-types pages (using https://github.com/wpilibsuite/sphinxext-rediraffe)

• Final look-through of docs

• Add v0.8.0 changelog and release commit

• Post PR merge TODOs

  • close all referenced issues
  • "you could even have a role that standardises the format, e.g. {myst-role}nb-exec-table
  • consider making xelatex the default
  • Make the conig schema the "source of truth" for available values and defaults, and auto-generate default_config from the schema
  • Update the jupytext version from ==1.6.0rc0 to ~=0.16.0, when it is released

[codecov]

Codecov Report

Merging #911 into master will increase coverage by 0.21%.
The diff coverage is 93.28%.

@@            Coverage Diff             @@
##           master     #911      +/-   ##
==========================================
+ Coverage   92.41%   92.63%   +0.21%     
==========================================
  Files           8        8              
  Lines         686      760      +74     
==========================================
+ Hits          634      704      +70     
- Misses         52       56       +4     

Flag	Coverage Δ
#pytests	92.63% <93.28%> (+0.21%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
jupyter_book/sphinx.py	84.21% <82.35%> (-1.51%)	⬇️
jupyter_book/commands/__init__.py	94.50% <91.12%> (-1.79%)	⬇️
jupyter_book/config.py	95.34% <95.34%> (ø)
jupyter_book/__init__.py	100.00% <100.00%> (ø)
jupyter_book/pdf.py	92.00% <100.00%> (-0.60%)	⬇️
jupyter_book/toc.py	93.14% <100.00%> (+0.07%)	⬆️
jupyter_book/utils.py	86.53% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 06b8134...266f11b. Read the comment docs.

[chrisjsewell]

Hey @mmcky @AakashGfude you might want to start looking through this.
I've finished on the main code changes, so just need to work on the document updates.

You can look through the commit history to see what's changed.
This will be a merge commit lol, since all the commits are well defined/formatted, but also combine to achieve the overarching PR goal.

[chrisjsewell]

Hey mmcky AakashGfude you might want to start looking through this.

and also @choldgraf, If you have a spare moment in between the diaper changes 😉

[chrisjsewell]

Ok, this is nearly done; just the addition of https://github.com/wpilibsuite/sphinxext-rediraffe, and writing the v0.8.0 CHANGELOG

I'm looking to merge this and release v0.8.0 in the next ~24-48 hours.
So speak now or forever hold your peace!

[phaustin]

reminder that we can remove https://github.com/executablebooks/jupyter-book/blob/upgrade/myst-nb-0.9/docs/advanced/advanced.md#working-on-windows

[chrisjsewell]

reminder that we can remove working-on-windows

Actually, in 0cf6f69, I have already modified this; to say that we do now support/test against Windows OS 😄 . But noted the notebook execution issue with Python 3.8 still remains

[chrisjsewell]

FYI also nearly fixed the jupytext issue, so no more myst-parser version incompatabilities or need for jupytext[myst] 😄 : mwouts/jupytext#602

[choldgraf]

I'm +1 on giving this a merge if others are 👍 as well. This is a big one and probably better to get it in sooner than later so people have a chance to play with it and see if it breaks things. I guess we should also cut a release relatively quickly since the docs will be even more outdated w/ the latest release once it's merged?

[chrisjsewell]

I guess we should also cut a release relatively quickly since the docs will be even more outdated w/ the latest release once it's merged?

Well that is what I meant in #911 (comment); I will literally add the "release" commit to this PR, merge, then immediately release v0.8

[chrisjsewell]

have a chance to play with it and see if it breaks things

If you want to do that, you need to do it now on this PR

[choldgraf]

Makes sense. Personally there's nothing I'd do other than to look at how the docs work,and they seem to be good to me. Maybe @mmcky can try this branch w the quantecon books? Perhaps @bmcfee can try with his book as well to make sure there's nothing unexpected

[chrisjsewell]

Yep sounds good 👍

[chrisjsewell]

The jupytext page is now actually written as an RMarkdown file 😄 https://deploy-preview-911--jupyter-book.netlify.app/file-types/jupytext.html

[chrisjsewell]

@AakashGfude @mmcky you may wish to check out https://deploy-preview-911--jupyter-book.netlify.app/content/figures.html#supported-image-formats, which is of relevance for LaTeX builds

[mmcky]

@AakashGfude @mmcky you may wish to check out https://deploy-preview-911--jupyter-book.netlify.app/content/figures.html#supported-image-formats, which is of relevance for LaTeX builds

thanks @chrisjsewell -- the html parsing is a nice feature as it brings it closer to compatibility with how jupyter notebooks get rendered in the notebook setting.

[chrisjsewell]

Now that's what I call a change log: https://deploy-preview-911--jupyter-book.netlify.app/reference/_changelog.html

[rodrigogiraoserrao]

Well mainly I just want someone(s) else to give it a second look, to make sure I'm not going to inadvertently break everyone's existing books 😬
Personally, I think the new logic is reasonable and, at the very least, we now have a way to "programmatically document" the behaviour (via the test cases), and also a way for users to directly understand how their config is being translated (via jb config sphinx).

A bit late, but looks good! Good job.