0.17.1: documentation build fails

[kloczek]

Describe the bug

context
Generating myst-nb sphinx docuemtation

expectation
It should be possible to generate documentation.

bug

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.1.3

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 279, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 223, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 456, in load_extension
    metadata = setup(app)
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/__init__.py", line 8, in setup
    from .sphinx_ext import sphinx_setup
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_ext.py", line 23, in <module>
    from myst_nb.sphinx_ import (
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_.py", line 16, in <module>
    from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer, create_warning
ImportError: cannot import name 'create_warning' from 'myst_parser.mdit_to_docutils.sphinx_' (/usr/lib/python3.8/site-packages/myst_parser/mdit_to_docutils/sphinx_.py)

Exception occurred:
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_.py", line 16, in <module>
    from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer, create_warning
ImportError: cannot import name 'create_warning' from 'myst_parser.mdit_to_docutils.sphinx_' (/usr/lib/python3.8/site-packages/myst_parser/mdit_to_docutils/sphinx_.py)
The full traceback has been saved in /tmp/sphinx-err-4e78y3dp.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

$ jupyter-book build mybook
ERROR ...

problem
This is a problem for people doing ___ because ___.

Reproduce the bug

Just run sphinx-build -n -T docs

List your environment

List of modules installed in build env

Package                       Version
----------------------------- -----------------
alabaster                     0.7.13
anyio                         3.6.2
appdirs                       1.4.4
argon2-cffi                   21.3.0
argon2-cffi-bindings          21.2.0
asttokens                     2.2.1
attrs                         22.2.0
Babel                         2.11.0
backcall                      0.2.0
beautifulsoup4                4.11.2
bleach                        5.0.0
build                         0.9.0
cffi                          1.15.1
charset-normalizer            3.0.1
click                         8.1.3
coconut                       2.2.0
colorama                      0.4.6
comm                          0.1.2
contourpy                     1.0.7
cPyparsing                    2.4.7.1.2.0
cssselect                     1.1.0
cycler                        0.11.0
debugpy                       1.6.6
decorator                     5.1.1
defusedxml                    0.7.1
distro                        1.8.0
docutils                      0.19
entrypoints                   0.4
exceptiongroup                1.0.0
executing                     1.2.0
extras                        1.0.0
fastjsonschema                2.16.1
fixtures                      4.0.0
fonttools                     4.38.0
gitdb                         4.0.10
GitPython                     3.1.30
gpg                           1.18.0-unknown
greenlet                      1.1.3
html5lib                      1.1
idna                          3.4
imagesize                     1.4.1
importlib-metadata            6.0.0
importlib-resources           5.12.0
iniconfig                     2.0.0
ipykernel                     6.20.2
ipython                       8.6.0
ipywidgets                    8.0.3
jedi                          0.18.2
Jinja2                        3.1.2
jsonschema                    4.17.3
jupyter-cache                 0.5.0
jupyter_client                7.4.9
jupyter_core                  5.1.3
jupyter-server                1.23.3
jupyter-server-mathjax        0.2.5
jupyter-sphinx                0.4.0
jupyterlab-pygments           0.1.2
jupyterlab-widgets            3.0.2
jupytext                      1.14.4
kiwisolver                    1.4.4
libcomps                      0.1.19
lxml                          4.9.2
Markdown                      3.4.1
markdown-it-py                2.1.0
MarkupSafe                    2.1.2
matplotlib                    3.6.3
matplotlib-inline             0.1.6
mdit-py-plugins               0.3.4
mdurl                         0.1.2
mistune                       2.0.5
mpmath                        1.2.1
myst-parser                   0.18.1
nbclient                      0.7.2
nbconvert                     7.2.9
nbdime                        3.1.1
nbformat                      5.7.3
nest-asyncio                  1.5.6
numpy                         1.24.2
olefile                       0.46
packaging                     23.0
pandas                        1.5.2
pandocfilters                 1.5.0
parso                         0.8.3
pbr                           5.9.0
pep517                        0.13.0
pexpect                       4.8.0
pickleshare                   0.7.5
Pillow                        9.4.0
pip                           22.3.1
pkgutil_resolve_name          1.3.10
platformdirs                  2.6.0
pluggy                        1.0.0
ply                           3.11
prometheus-client             0.16.0
prompt-toolkit                3.0.36
psutil                        5.9.2
ptyprocess                    0.7.0
pure-eval                     0.2.2
pycparser                     2.21
pydata-sphinx-theme           0.12.0
Pygments                      2.14.0
PyGObject                     3.43.1.dev0
pyparsing                     3.0.9
pyrsistent                    0.19.3
pytest                        7.2.1
pytest-datadir                1.4.1
pytest_param_files            0.3.4
pytest-regressions            2.4.2
python-dateutil               2.8.2
pytz                          2022.4
PyYAML                        6.0
pyzmq                         24.0.1
requests                      2.28.2
rpm                           4.17.0
scour                         0.38.2
Send2Trash                    1.8.0
setuptools                    65.6.3
six                           1.16.0
smartypants                   2.0.1
smmap                         5.0.0
sniffio                       1.2.0
snowballstemmer               2.2.0
soupsieve                     2.4
Sphinx                        6.1.3
sphinx-book-theme             0.3.3
sphinx-copybutton             0.5.1
sphinx_design                 0.3.0
sphinx-togglebutton           0.3.2
sphinxcontrib-applehelp       1.0.4
sphinxcontrib-devhelp         1.0.2.dev20230202
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1.dev20230128
sphinxcontrib-qthelp          1.0.3.dev20230128
sphinxcontrib-serializinghtml 1.1.5
SQLAlchemy                    2.0.4.dev0
stack-data                    0.6.2
sympy                         1.10.1
tabulate                      0.9.0
terminado                     0.17.1
testtools                     2.5.0
tinycss2                      1.2.1
toml                          0.10.2
tomli                         2.0.1
tornado                       6.2
traitlets                     5.8.1
typing_extensions             4.4.0
typogrify                     2.0.7
urllib3                       1.26.12
wcwidth                       0.2.6
webencodings                  0.5.1
websocket-client              1.5.1
wheel                         0.38.4
widgetsnbextension            4.0.5
zipp                          3.13.0

[agoose77]

@kloczek is this still a problem for the latest mystnb release? Can you confirm that you have a compatible version of myst-parser installed for myst-nb? :)

[kloczek]

@kloczek is this still a problem for the latest mystnb release? Can you confirm that you have a compatible version of myst-parser installed for myst-nb? :)

I've reported issue against latest 0.17.1 and I just checked there is no any new version so .. yes it still the issue 😋

No I have no installed myst-nb because build log is from packaging `myst-nb.
I'm using below patch

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,6 +1,8 @@
 # Configuration file for the Sphinx documentation builder.
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os
+import sys
+sys.path.insert(0, os.path.abspath(".."))

 # -- Project information -----------------------------------------------------

to allow sphinx find myst-nb modules.
That kind of conf.py alteration is mentioned in sphinx example conf.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

[kloczek]

In other words that patch guarantees that documentation is generated against in source tree mys-mb which is 0.17.1.

[agoose77]

Ah, I'm following — and the docs don't build locally for me either, although due to a different error. With a fresh solve, I ran into #486 and also noted that the coconut dependency is pulling in a poorly maintained cpyparsing library. I'll make another PR in future to propose a different kernel instead of coconut.

[kloczek]

Ah, I'm following — and the docs don't build locally for me either, although due to a different error. With a fresh solve, I ran into #486 and also noted that the coconut dependency is pulling in a poorly maintained cpyparsing library. I'll make another PR in future to propose a different kernel instead of coconut.

Just tested that PR on top of the release and documentation build still fails.

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v6.1.3

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 279, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 223, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 456, in load_extension
    metadata = setup(app)
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/__init__.py", line 8, in setup
    from .sphinx_ext import sphinx_setup
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_ext.py", line 23, in <module>
    from myst_nb.sphinx_ import (
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_.py", line 16, in <module>
    from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer, create_warning
ImportError: cannot import name 'create_warning' from 'myst_parser.mdit_to_docutils.sphinx_' (/usr/lib/python3.8/site-packages/myst_parser/mdit_to_docutils/sphinx_.py)

Exception occurred:
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_.py", line 16, in <module>
    from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer, create_warning
ImportError: cannot import name 'create_warning' from 'myst_parser.mdit_to_docutils.sphinx_' (/usr/lib/python3.8/site-packages/myst_parser/mdit_to_docutils/sphinx_.py)
The full traceback has been saved in /tmp/sphinx-err-kdukc65s.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[tkloczko@pers-jacek SPECS]$ cat /tmp/sphinx-err-kdukc65s.log
# Platform:         linux; (Linux-6.1.10-200.fc37.x86_64-x86_64-with-glibc2.34)
# Sphinx version:   6.1.3
# Python version:   3.8.16 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.1.2
# Pygments version: 2.14.0

# Last messages:


# Loaded extensions:


# Traceback:
Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 279, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 223, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 456, in load_extension
    metadata = setup(app)
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/__init__.py", line 8, in setup
    from .sphinx_ext import sphinx_setup
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_ext.py", line 23, in <module>
    from myst_nb.sphinx_ import (
  File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-0.17.1/myst_nb/sphinx_.py", line 16, in <module>
    from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer, create_warning
ImportError: cannot import name 'create_warning' from 'myst_parser.mdit_to_docutils.sphinx_' (/usr/lib/python3.8/site-packages/myst_parser/mdit_to_docutils/sphinx_.py)

Just in case I'm usimg myst-parser 1.0.0.

BTW is it possible to add that conf.,py patch to you git tee? (feel free to commit it or let me know if you want me to create PR)

[agoose77]

BTW is it possible to add that conf.,py patch to you git tee? (feel free to commit it or let me know if you want me to create PR)

What's wrong with an editable install?

BTW is it possible to add that conf.,py patch to you git tee? (feel free to commit it or let me know if you want me to create PR)

myst-nb only declares support for the 0.18.* series, so 1.0.0 is not supported:

MyST-NB/pyproject.toml

Line 42 in 385c4a7

"myst-parser~=0.18.0",

[kloczek]

BTW is it possible to add that conf.,py patch to you git tee? (feel free to commit it or let me know if you want me to create PR)

What's wrong with an editable install?

As I wrote with such patch it is possible to build documentation without remeber to do any operations before (it can be done just after clone repo).

myst-nb only declares support for the 0.18.* series, so 1.0.0 is not supported:

MyST-NB/pyproject.toml

Line 42 in 385c4a7

"myst-parser~=0.18.0",

OK. Do you have any plans to support 1.0.0? 🤔 (just asking ..)

[kloczek]

Will close this ticket as 1.0.0 has been released.
Documentation build still fails but will put fresh details in new ticket.