MyST-NB

MyST-NB copied to clipboard

Description / Summary

When both *.ipynb and *.md files are present (synced, for example, with jupytext), one encounters WARNING: multiple files found for the document warnings. It would be nice if there was a clear way to suppress these expressed in the documentation.

Value / benefit

This would help users who use jupytext to synchronize files in different formats. For example, when I don't need to futz with output, I much rather edit the *.md files directly, but, if I am updating the code examples, sometimes using jupyter is faster.

Implementation details

Currently, myst-nb adds both *.md and *.ipynb suffixes in __init__.py. One somewhat drastic work-around is for users to include the following in their conf.py file:

def setup(app):
    # Ignore .ipynb files
    app.registry.source_suffix.pop(".ipynb", None)

However, it would be better if somehow the warning could simply be suppressed (I looked at the suppress_warnings Sphinx configuration option, but it does not seem to be useful), or maybe if there was a way of preventing ".ipynb" from being inserted.

Tasks to complete

• [] Decide if this should just be a documentation fix.
• [] If so, update the documentations.
• [] If more should be done, then adjust the code and provide a suitable configuration option.

I'm having the same issue sphinx-gallery which creates .rst, .ipynb and .py files at runtime:

WARNING: multiple files found for the document "examples/test":
    ['examples/test.ipynb','examples/test.py', 'examples/test.rst']

The workaround does work for me too 👍

I've experienced this as well when using both myst-nb and sphinx-gallery as reported by @seignovert .

Edit: Ignore below - I was fooled into thinking it worked by not realizing I had a clean build.

---

I just wanted to add a minor adjustment to the workaround from the OP: rather than popping from the source_suffix in the app, you can prevent the .ipynb extension from being registered entirely by adding the following to your conf.py file:

source_suffix = {".ipynb": None}

I picked up this idea from this config note in the myst-nb docs. Of course, it still doesn't doesn't solve the problem if your have content written in both .md and .ipynb format, but it might fit the bill for the following from the OP:

or maybe if there was a way of preventing ".ipynb" from being inserted.

Note another way to do this I think is to use a root_prefix (see https://jupytext.readthedocs.io/en/latest/config.html?highlight=root_prefix#configuring-paired-notebooks-globally), to put the the files in different folders:

# Pair notebooks in subfolders of 'notebooks' to scripts in subfolders of 'scripts'
formats = "notebooks///ipynb,scripts///myst"

then you can ignore the folder with the notebooks in: exclude_patterns = ["notebooks"]

That's a nice solution for the jupytext/pairing use-case. The sphinx-gallery case is a bit different since it automatically generates the .rst and .ipynb files in the same location. There may be a way to configure that differently as well, but the default configuration results in these warnings.

I had the same issue with sphinx-gallery, and I've circumvented it by specifically excluding the auto-generated .py and .ipynb gallery files as sources. This forces Sphinx to render the .rst files and it stops complaining about "multiple files found for the document".

In Sphinx's conf.py file:

exclude_patterns = [
    ...,
    # exclude .py and .ipynb files in auto_examples generated by sphinx-gallery
    # this is to prevent sphinx from complaining about duplicate source files
    "auto_examples/*.ipynb",
    "auto_examples/*.py",
]

Using sphinx-gallery and same issue here. @niksirbi fix works great. In case you structured your gallery with sub directories this slightly more general expression worked best for me:

exclude_patterns = [
    ...,
    # exclude .py and .ipynb files in auto_examples generated by sphinx-gallery
    # this is to prevent sphinx from complaining about duplicate source files
    "auto_examples/**/*.ipynb",
    "auto_examples/**/*.py",
]