search

executablebooks / MyST-NB

Parse and execute ipynb files in Sphinx
https://myst-nb.readthedocs.io
BSD 3-Clause "New" or "Revised" License
202 stars 81 forks source link

myst_nb vs myst_parser issues #357

Open Phlya opened 2 years ago

Phlya commented 2 years ago

Describe the problem

Hello! Sorry the issue is a little confusing, but that's maybe because I am new to this, and because I am myself a little confused.

I was having a strange issue that nbsphinx was getting stuck on a notebook and breaking the build of my docs. So I decided to try myst_nb instead, and magically the notebook was rendering perfectly. However, because myst_nb also supports .md files, I had a clash with my use of m2r2, which I used to mdinclude my readme from an outside folder into the index.rst. However myst_nb doesn't support mdinclude, and moreover doesn't seem to support the syntax to achieve that from myst_parser described e.g. here: https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#include-rst-files-into-a-markdown-file (or at least it doesn't work for me!). Then I decided to try myst_parser instead of myst_nb, hoping it would allow me to include notebooks and also include the readme file. However it breaks on my notebook just like nbsphinx did!

Link to your repository or website

https://github.com/open2c/coolpuppy

Steps to reproduce

Not sure how to reproduce it, since I don't know what's wrong with my notebook that nbsphinx and myst_parser break when parsing it, but it's in docs/source/Examples/Walkthough_API.ipynb

The version of Python you're using

3.8.10

Your operating system

Ubuntu 20.04

Versions of your packages

myst-nb 0.12.3 myst-parser 0.13.7 sphinx 3.5.4

Additional context

No response

welcome[bot] commented 2 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

Phlya commented 2 years ago

OK, a mistake I made is that that code to include the readme should be within a md file, and so I needed to convert my index.rst to index.md - which I have done and it now works! But I guess the discrepancy in parsing of a notebook between myst_nb vs myst_parser still remains a question for me? But feel free to close this issue if it's not an issue :) Thanks!

choldgraf commented 2 years ago

hmmmm - one possibility is that this is due to version mismatch issues between myst-parser and MyST-NB. There should be no difference in syntax between them, since MyST-NB uses the MyST parser for all markdown parsing.

We need to release a new version of MyST-NB soon - I believe that this issue is the major remaining one to resolve: https://github.com/executablebooks/MyST-NB/pull/356

Then we can release a new MyST-NB and it'll come with the latest MyST Parser (which is 0.15 I think)

So in the meantime you could try:

do either of those work?

mmcky commented 2 years ago

We have just released myst-nb=0.13 -- that might be worth a try in a new environment to see if you still get the same issue. This release includes the latest myst-parser version. 

pip install myst-nb --upgrade
Phlya commented 2 years ago

Apologies for the silence. I have just been experimenting with a new environment with myst-nb 0.13.0 and myst-parser 0.15.2, and still I get this discrepancy that myst_nb parses notebooks with no issues, while myst_parser freezes.