Clean up Sphinx and MyST warnings in documentation build
Author: hwhsu1231Created Aug 17, 2026Updated Aug 17, 2026
Problem Description
There are lots of warnings when building the Jupyter documentation:
/path/to/jupyter/repo/docs/source/community/sample_scripts.md:100: WARNING: Document or section may not begin with a transition. [docutils]
/path/to/jupyter/repo/docs/source/projects/doc-proj-categories.rst:48: ERROR: Duplicate target name, cannot be used as a unique reference: "ipython". [docutils]
/path/to/jupyter/repo/docs/source/projects/kernels.rst:35: WARNING: duplicate term description of IPython, other instance in glossary
/path/to/jupyter/repo/docs/source/projects/user-interfaces.rst:10: WARNING: duplicate term description of JupyterLab, other instance in glossary
/path/to/jupyter/repo/docs/source/community/host-guide.md:5: WARNING: 'myst' cross-reference target not found: 'meeting-script-and-checklist' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/community/host-guide.md:32: WARNING: local id not found in doc 'community/sample_scripts': 'meeting-time-slot-request' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/community/host-guide.md:36: WARNING: local id not found in doc 'community/sample_scripts': 'hackmd-note-template' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/community/host-guide.md:48: WARNING: local id not found in doc 'community/sample_scripts': 'blog-post' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/community/host-guide.md:53: WARNING: local id not found in doc 'community/sample_scripts': 'sample-scripts' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/community/host-guide.md:163: WARNING: 'myst' cross-reference target not found: ' https://discourse.jupyter.org/t/jupyter-community-calls/668/102?u=ruv7' [myst.xref_missing]
/path/to/jupyter/repo/docs/source/projects/architecture/content-architecture.rst:175: WARNING: unknown document: 'z2jh:administrator/architecture' [ref.doc]
/path/to/jupyter/repo/docs/source/projects/architecture/content-architecture.rst:176: WARNING: undefined label: 'bhub:diagram' [ref.ref]The following commands are what I used:
BRANCH=master
COMMIT=6b5eb0f469c7bc3ea43d6d2a0ba1057853c9a3a5
git clone --branch=$BRANCH https://github.com/jupyter/jupyter.git
cd jupyter
git checkout $COMMIT
export LANGUAGE=en_US LANG=en_US.UTF-8
uv run --with-requirements docs/doc-requirements.txt make -C docs htmlhwhsu1231@vb-kubuntu:/media/hwhsu1231/KubuntuData/Repo/testing$ BRANCH=master
COMMIT=6b5eb0f469c7bc3ea43d6d2a0ba1057853c9a3a5
git clone --branch=$BRANCH https://github.com/jupyter/jupyter.git
cd jupyter
git checkout $COMMIT
export LANGUAGE=en_US LANG=en_US.UTF-8
uv run --with-requirements docs/doc-requirements.txt make -C docs html
Cloning into 'jupyter'...
remote: Enumerating objects: 5650, done.
remote: Counting objects: 100% (1469/1469), done.
remote: Compressing objects: 100% (374/374), done.
remote: Total 5650 (delta 1335), reused 1111 (delta 1095), pack-reused 4181 (from 3)
Receiving objects: 100% (5650/5650), 8.00 MiB | 9.67 MiB/s, done.
Resolving deltas: 100% (3794/3794), done.
Note: switching to '6b5eb0f469c7bc3ea43d6d2a0ba1057853c9a3a5'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
git switch -c <new-branch-name>
Or undo this operation with:
git switch -
Turn off this advice by setting config variable advice.detachedHead to false
HEAD is now at 6b5eb0f Merge pull request #830 from jasongrout/jupyter-banner
make: Entering directory '/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs'
sphinx-build -b html -d build/doctrees source build/html
Running Sphinx v9.1.0
loading translations [en]... done
making output directory... done
Converting `source_suffix = ['.rst', '.md']` to `source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'}`.
loading intersphinx inventory 'hub' from https://jupyterhub.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'ipyparallel' from https://ipyparallel.readthedocs.io/en/stable/objects.inv ...
loading intersphinx inventory 'ipython' from https://ipython.readthedocs.io/en/stable/objects.inv ...
loading intersphinx inventory 'ipywidgets' from https://ipywidgets.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'jupyterclient' from https://jupyter-client.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'jupytercore' from https://jupyter-core.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'lab' from https://jupyterlab.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'nbconvert' from https://nbconvert.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'nbformat' from https://nbformat.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'notebook' from https://jupyter-notebook.readthedocs.io/en/stable/objects.inv ...
loading intersphinx inventory 'traitlets' from https://traitlets.readthedocs.io/en/latest/objects.inv ...
loading intersphinx inventory 'qtconsole' from https://qtconsole.readthedocs.io/en/stable/objects.inv ...
myst v5.1.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=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_sort=True, 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, strikethrough_single_tilde=False, colon_fence_exact_match=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 22 po files that are out of date
writing output... [100%] locale/en/LC_MESSAGES/developer-docs.mo
building [html]: targets for 115 source files that are out of date
updating environment: [new config] 115 added, 0 changed, 0 removed
reading sources... [100%] what_is_jupyter
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/community-call-notes/2025-september.md:40: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/sample_scripts.md:100: WARNING: Document or section may not begin with a transition. [docutils]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/projects/doc-proj-categories.rst:48: ERROR: Duplicate target name, cannot be used as a unique reference: "ipython". [docutils]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/projects/kernels.rst:35: WARNING: duplicate term description of IPython, other instance in glossary
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/projects/user-interfaces.rst:10: WARNING: duplicate term description of JupyterLab, other instance in glossary
looking for now-outdated files... none found
pickling environment... done
checking consistency... /media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/sample_scripts.md: WARNING: document isn't included in any toctree [toc.not_included]
done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to /media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/build/html/_static/basic.css
Writing evaluated template result to /media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/build/html/_static/documentation_options.js
Writing evaluated template result to /media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/build/html/_static/language_data.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] what_is_jupyter
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:5: WARNING: 'myst' cross-reference target not found: 'meeting-script-and-checklist' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:32: WARNING: local id not found in doc 'community/sample_scripts': 'meeting-time-slot-request' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:36: WARNING: local id not found in doc 'community/sample_scripts': 'hackmd-note-template' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:48: WARNING: local id not found in doc 'community/sample_scripts': 'blog-post' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:53: WARNING: local id not found in doc 'community/sample_scripts': 'sample-scripts' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/community/host-guide.md:163: WARNING: 'myst' cross-reference target not found: ' https://discourse.jupyter.org/t/jupyter-community-calls/668/102?u=ruv7' [myst.xref_missing]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/projects/architecture/content-architecture.rst:175: WARNING: unknown document: 'z2jh:administrator/architecture' [ref.doc]
/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs/source/projects/architecture/content-architecture.rst:176: WARNING: undefined label: 'bhub:diagram' [ref.ref]
generating indices... genindex done
writing additional pages... search done
copying images... [100%] _static/_images/jupyter_software_diagram_alpha.png
dumping search index in English (code: en)... done
dumping object inventory... done
Writing redirects...
(good) content-quickstart.html --> start/index.html
(good) tryjupyter.html --> start/index.html
build succeeded, 14 warnings.
The HTML pages are in build/html.
Build finished. The HTML pages are in build/html.
make: Leaving directory '/media/hwhsu1231/KubuntuData/Repo/testing/jupyter/docs'
hwhsu1231@vb-kubuntu:/media/hwhsu1231/KubuntuData/Repo/testing/jupyter$ Proposed Solutions
Fix the warning messages step by step based on the error outputs.
Source: jupyter/jupyter