MyST-NB
MyST-NB copied to clipboard
executablebooks
1.0.0: documentation build fails
Describe the bug
Looks like documentation build still fail.
Reproduce the bug
I'm building documentation without have myst-nb installed.
It is possible to do that with 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 -----------------------------------------------------
That kind of hack is listed in example sphinx conf.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file
With that patch documentation build fails with
+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.1.2
making output directory... done
CoconutWarning: Failed to update Coconut Jupyter kernel installation; the 'coconut' kernel might not work properly as a result (try again with 'sudo').
Coconut: Installing Jupyter kernels 'coconut_py', 'coconut_py2', 'coconut_py3'...
Coconut: Successfully installed Jupyter kernels: 'coconut_py', 'coconut_py2', 'coconut_py3'
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'dollarmath', 'colon_fence', 'deflist', 'amsmath', 'html_image'}, disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
myst-nb v1.0.0rc0: NbParserConfig(custom_formats={'.Rmd': ('jupytext.reads', {'fmt': 'Rmd'}, False)}, metadata_key='mystnb', cell_metadata_key='mystnb', kernel_rgx_aliases={}, eval_name_regex='^[a-zA-Z_][a-zA-Z0-9_]*$', execution_mode='cache', execution_cache_path='', execution_excludepatterns=(), execution_timeout=60, execution_in_temp=False, execution_allow_errors=False, execution_raise_on_error=False, execution_show_tb=False, merge_streams=False, render_plugin='default', remove_code_source=False, remove_code_outputs=False, code_prompt_show='Show code cell {type}', code_prompt_hide='Hide code cell {type}', number_source_lines=False, output_stderr='show', render_text_lexer='myst-ansi', render_error_lexer='ipythontb', render_image_options={}, render_figure_options={}, render_markdown_format='commonmark', output_folder='build', append_css=True, metadata_to_fm=False)
Using jupyter-cache at: /home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/build/sphinx/.jupyter_cache
loading intersphinx inventory from https://docs.python.org/3.8/objects.inv...
loading intersphinx inventory from https://jupyterbook.org/objects.inv...
loading intersphinx inventory from https://myst-parser.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://markdown-it-py.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://nbclient.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://nbformat.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
intersphinx inventory has moved: https://jupyterbook.org/objects.inv -> https://jupyterbook.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 22 added, 0 changed, 0 removed
reading sources... [ 9%] authoring/custom-formats
Traceback (most recent call last):
File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 290, in build_main
app.build(args.force_all, args.filenames)
File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 351, in build
self.builder.build_update()
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 287, in build_update
self.build(['__all__'], to_build)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 310, in build
updated_docnames = set(self.read())
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 417, in read
self._read_serial(docnames)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 438, in _read_serial
self.read_doc(docname)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 494, in read_doc
publisher.publish()
File "/usr/lib/python3.8/site-packages/docutils/core.py", line 234, in publish
self.document = self.reader.read(self.source, self.parser,
File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 104, in read
self.parse()
File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 76, in parse
self.parser.parse(self.input, document)
File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/myst_nb/sphinx_.py", line 137, in parse
nb_renderer: NbElementRenderer = load_renderer(renderer_name)(
File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/myst_nb/core/render.py", line 862, in load_renderer
raise EntryPointError(f"No Entry Point found for {RENDER_ENTRY_GROUP}:{name}")
myst_nb.core.render.EntryPointError: No Entry Point found for myst_nb.renderers:default
Exception occurred:
File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/myst_nb/core/render.py", line 862, in load_renderer
raise EntryPointError(f"No Entry Point found for {RENDER_ENTRY_GROUP}:{name}")
myst_nb.core.render.EntryPointError: No Entry Point found for myst_nb.renderers:default
The full traceback has been saved in /tmp/sphinx-err-tz5bt25a.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-tz5bt25a.log
# Platform: linux; (Linux-6.4.8-200.fc38.x86_64-x86_64-with-glibc2.34)
# Sphinx version: 7.1.2
# Python version: 3.8.18 (CPython)
# Docutils version: 0.20.1
# Jinja2 version: 3.1.2
# Pygments version: 2.16.1
# Last messages:
# [new config]
# 22 added, 0 changed, 0 removed
# reading sources... [ 5%]
# authoring/basics
#
# reading sources... [ 9%]
# authoring/custom-formats
#
# Loaded extensions:
# sphinx.ext.mathjax (7.1.2)
# alabaster (0.7.13)
# sphinxcontrib.applehelp (1.0.4)
# sphinxcontrib.devhelp (1.0.2)
# sphinxcontrib.htmlhelp (2.0.4)
# sphinxcontrib.serializinghtml (1.1.9)
# sphinxcontrib.qthelp (1.0.3)
# myst_nb (1.0.0rc0)
# sphinx_copybutton (0.5.1)
# sphinx_book_theme (unknown version)
# sphinx.ext.intersphinx (7.1.2)
# sphinx.ext.autodoc.preserve_defaults (7.1.2)
# sphinx.ext.autodoc.type_comment (7.1.2)
# sphinx.ext.autodoc.typehints (7.1.2)
# sphinx.ext.autodoc (7.1.2)
# sphinx.ext.viewcode (7.1.2)
# sphinx_design (0.5.0)
# Traceback:
Traceback (most recent call last):
File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 290, in build_main
app.build(args.force_all, args.filenames)
File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 351, in build
self.builder.build_update()
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 287, in build_update
self.build(['__all__'], to_build)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 310, in build
updated_docnames = set(self.read())
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 417, in read
self._read_serial(docnames)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 438, in _read_serial
self.read_doc(docname)
File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 494, in read_doc
publisher.publish()
File "/usr/lib/python3.8/site-packages/docutils/core.py", line 234, in publish
self.document = self.reader.read(self.source, self.parser,
File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 104, in read
self.parse()
File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 76, in parse
self.parser.parse(self.input, document)
File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/myst_nb/sphinx_.py", line 137, in parse
nb_renderer: NbElementRenderer = load_renderer(renderer_name)(
File "/home/tkloczko/rpmbuild/BUILD/MyST-NB-1.0.0/myst_nb/core/render.py", line 862, in load_renderer
raise EntryPointError(f"No Entry Point found for {RENDER_ENTRY_GROUP}:{name}")
myst_nb.core.render.EntryPointError: No Entry Point found for myst_nb.renderers:default
List your environment
Here is list of installed modules in build env
Package Version
----------------------------- -----------
alabaster 0.7.13
anyio 3.7.1
argon2-cffi 23.1.0
argon2-cffi-bindings 21.2.0
asttokens 2.2.1
attrs 23.1.0
Babel 2.13.1
backcall 0.2.0
beautifulsoup4 4.12.2
bleach 6.1.0
build 1.0.0
cffi 1.16.0
charset-normalizer 3.3.1
click 8.1.7
coconut 3.0.1
colorama 0.4.6
comm 0.1.4
contourpy 1.0.7
cppclean 0.13
cPyparsing 2.4.7.2.2.3
cycler 0.12.1
debugpy 1.8.0
decorator 5.1.1
defusedxml 0.7.1
distro 1.8.0
docutils 0.20.1
exceptiongroup 1.1.3
executing 1.2.0
fastjsonschema 2.18.0
fonttools 4.43.1
gitdb 4.0.10
GitPython 3.1.40
gpg 1.22.0
greenlet 2.0.2
html5lib 1.1
idna 3.4
imagesize 1.4.1
importlib-metadata 6.8.0
importlib-resources 6.1.0
iniconfig 2.0.0
installer 0.7.0
ipykernel 6.26.0
ipython 8.12.0
ipywidgets 8.0.3
jedi 0.19.0
Jinja2 3.1.2
jsonschema 4.19.1
jsonschema-specifications 2023.7.1
jupyter-cache 0.5.0
jupyter_client 8.4.0
jupyter_core 5.3.1
jupyter-events 0.8.0
jupyter_server 2.9.1
jupyter-server-mathjax 0.2.6
jupyter_server_terminals 0.4.4
jupyter-sphinx 0.4.0
jupyterlab-pygments 0.1.2
jupyterlab-widgets 3.0.8
jupytext 1.15.2
kiwisolver 1.4.5
markdown-it-py 3.0.0
MarkupSafe 2.1.3
matplotlib 3.6.3
matplotlib-inline 0.1.6
mdit-py-plugins 0.4.0
mdurl 0.1.2
mistune 2.0.5
mpmath 1.3.0
myst-parser 2.0.0
nbclient 0.8.0
nbconvert 7.8.0
nbdime 3.2.1
nbformat 5.9.2
nest-asyncio 1.5.8
numpy 1.24.4
olefile 0.46
overrides 7.4.0
packaging 23.2
pandas 2.0.3
pandocfilters 1.5.0
parso 0.8.3
pexpect 4.8.0
pickleshare 0.7.5
Pillow 10.1.0
pkgutil_resolve_name 1.3.10
platformdirs 3.11.0
pluggy 1.3.0
ply 3.11
prometheus-client 0.17.1
prompt-toolkit 3.0.39
psutil 5.9.5
ptyprocess 0.7.0
pure-eval 0.2.2
pycparser 2.21
pydata-sphinx-theme 0.12.0
Pygments 2.16.1
pyparsing 3.1.1
pyproject_hooks 1.0.0
pytest 7.4.3
pytest-datadir 1.5.0
pytest_param_files 0.6.0
pytest-regressions 2.5.0
python-dateutil 2.8.2
python-json-logger 2.0.7
pytz 2023.3
PyYAML 6.0.1
pyzmq 25.1.1
referencing 0.30.2
requests 2.31.0
rfc3339-validator 0.1.4
rfc3986-validator 0.1.1
rpds-py 0.10.6
ruamel.yaml 0.18.2
ruamel.yaml.clib 0.2.7
Send2Trash 1.8.2
setuptools 68.2.2
six 1.16.0
smmap 5.0.0
sniffio 1.3.0
snowballstemmer 2.2.0
soupsieve 2.5
Sphinx 7.1.2
sphinx-book-theme 0.3.3
sphinx-copybutton 0.5.1
sphinx_design 0.5.0
sphinx-togglebutton 0.3.2
sphinxcontrib-applehelp 1.0.4
sphinxcontrib-devhelp 1.0.2
sphinxcontrib-htmlhelp 2.0.4
sphinxcontrib-jsmath 1.0.1
sphinxcontrib-qthelp 1.0.3
sphinxcontrib-serializinghtml 1.1.9
SQLAlchemy 2.0.22
stack-data 0.6.3
sympy 1.12
tabulate 0.9.0
terminado 0.17.1
tinycss2 1.2.1
toml 0.10.2
tomli 2.0.1
tornado 6.3.3
traitlets 5.11.2
typing_extensions 4.8.0
urllib3 1.26.18
wcwidth 0.2.8
webencodings 0.5.1
websocket-client 1.6.4
wheel 0.41.2
widgetsnbextension 4.0.9
zipp 3.17.0
OK, I can see why this would happen. We use entrypoints to facilitate extensibility. These entrypoints require a package to be installed. This isn't something that we can really fix - is there a reason that you can't run sphinx with the package installed?
Building package I cannot install anything (build is performed from non-root account) and packaging procedure should not be about installing anything. To be honest I don't understand this approach with entry points .. 🤔
I don't think there should be anything wrong with requiring a package to be installed in order for its documentation to be built. I am not intimately familiar with OS packaging processes, however. Is it possible for you to create a virtual environment that is used during building?
Let me show you something
[tkloczko@pers-jacek SPECS]$ grep %sphinx_build_man -l python-*spec| wc -l; ls -1 python-*.spec | wc -l
671
1217
So it means that I have +1.2k rpm packa build procedures in form of rpm spec files and amongst those files +670 is able to produce man page using sphinx.
That %sphinx_build_man rpm macro looks like below:
[tkloczko@pers-jacek SPECS]$ rpm -E %sphinx_build_man
\
PBR_VERSION=%{version} \
PDM_BUILD_SCM_VERSION=%{version} \
SETUPTOOLS_SCM_PRETEND_VERSION=%{version} \
JARACO_PACKAGING_SPHINX_WHEEL=$(ls -1 $PWD/dist/*whl) \
/usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Amongst all those python modules literally NONE requires such special approach which is in this case ..
Q: what makes impossible to use only source tree without installing anything to build documentation? Maybe it is kind of only artificial assumption which is easy to remove from documentation build procedure? 🤔
Building documentation out of ONLY source tree has IMO huge advantage because it provides 100% guarantee that documentation will be build out of source tree ano not out of installed module (which may ne not the same version). 😋