Docs: Fixes warnings and other noisy build messages

docs/conf.py

@@ -72,24 +72,23 @@
 exclude_patterns = ["_build"]
 default_role = "obj"
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.6/", None),
+    "python": ("https://docs.python.org/3.10/", None),
     "django": (
-        "https://docs.djangoproject.com/en/2.2/",
-        "https://docs.djangoproject.com/en/2.2/_objects/",
+        "https://docs.djangoproject.com/en/stable/",
+        "https://docs.djangoproject.com/en/stable/_objects/",
     ),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "pip": ("https://pip.pypa.io/en/stable/", None),
-    "nbsphinx": ("https://nbsphinx.readthedocs.io/en/0.8.6/", None),
-    "myst-nb": ("https://myst-nb.readthedocs.io/en/v0.12.3/", None),
-    "ipywidgets": ("https://ipywidgets.readthedocs.io/en/7.6.3/", None),
+    "nbsphinx": ("https://nbsphinx.readthedocs.io/en/latest/", None),
+    "myst-nb": ("https://myst-nb.readthedocs.io/en/stable/", None),
+    "ipywidgets": ("https://ipywidgets.readthedocs.io/en/stable/", None),
     "jupytext": ("https://jupytext.readthedocs.io/en/stable/", None),
     "ipyleaflet": ("https://ipyleaflet.readthedocs.io/en/latest/", None),
     "poliastro": ("https://docs.poliastro.space/en/stable/", None),
     "qiskit": ("https://qiskit.org/documentation/", None),
-    "myst-parser": ("https://myst-parser.readthedocs.io/en/v0.15.1/", None),
+    "myst-parser": ("https://myst-parser.readthedocs.io/en/stable/", None),
     "writethedocs": ("https://www.writethedocs.org/", None),
-    "jupyterbook": ("https://jupyterbook.org/", None),
-    "myst-parser": ("https://myst-parser.readthedocs.io/en/v0.15.1/", None),
+    "jupyterbook": ("https://jupyterbook.org/en/stable/", None),
     "rst-to-myst": ("https://rst-to-myst.readthedocs.io/en/stable/", None),
     "rtd": ("https://docs.readthedocs.io/en/stable/", None),
     "rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
@@ -169,6 +168,7 @@
     "class": "tooltip",  # for Python Sphinx Domain
     "ref": "tooltip",  # for hoverxref_auto_ref config
     "confval": "tooltip",  # for custom object
+    "term": "tooltip",  # for glossaries
 }
 
 rst_epilog = """

docs/user/guides/jupyter.rst

@@ -343,9 +343,9 @@ However, there are some differences between them:
   whereas MyST-NB does not have such functionality at the moment
   (see :ref:`notebook-galleries` for more information about galleries).
 - MyST-NB allows embedding Python objects coming from the notebook in the documentation
-  (read :ref:`their "glue" documentation <myst-nb:glue>`
+  (read :doc:`their "glue" documentation <myst-nb:render/glue>`
   for more information)
-  and provides more sophisticated :ref:`error reporting <myst-nb:start/error-reporting>`
+  and provides more sophisticated :doc:`error reporting <myst-nb:computation/execute>`
   than the one nbsphinx has.
 - The visual appearance of code cells and their outputs is slightly different:
   nbsphinx renders the cell numbers by default,
@@ -363,8 +363,7 @@ Deciding which one to use depends on your use case. As general recommendations:
   nbsphinx is the right choice.
 - If you want to leverage a more optimized execution workflow
   and a more streamlined parsing mechanism,
-  as well as some of the unique MyST-NB functionalities
-  (``glue``, better error reporting)
+  as well as some of the unique MyST-NB functionalities,
   you should use MyST-NB.
 
 Alternative notebook formats

docs/user/guides/migrate-rest-myst.md

@@ -8,12 +8,14 @@ thanks to a number of extensions.
 The most powerful of such extensions is {doc}`MyST-Parser <myst-parser:index>`,
 which implements a CommonMark-compliant, extensible Markdown dialect
 with support for the Sphinx roles and directives that make it so useful.
+
 In this guide, you will find
 how you can start writing Markdown in your existing reStructuredText project,
 or migrate it completely.
 
-If, instead of migrating, you are starting a new project from scratch,
-have a look at {doc}`myst-parser:sphinx/intro`.
+If, **instead of migrating**, you are starting a new project from scratch,
+have a look at {doc}`myst-parser:intro`.
+If you are starting a **project for Jupyter**, you can start with Jupyter Book, which uses ``MyST-Parser``, see the official Jupyter Book tutorial: {doc}`jupyterbook:start/your-first-book`
 
 ## Writing your content both in reStructuredText and MyST
 
@@ -25,8 +27,8 @@ and some others in reStructuredText, for whatever reason.
 Luckily, Sphinx supports reading both types of markup at the same time without problems.
 
 To start using MyST in your existing Sphinx project,
-first {ref}``install the `myst-parser` Python package <myst-parser:sphinx/intro.md#install-the-myst-parser>``
-and then {ref}`enable it on your configuration <myst-parser:parse-with-sphinx>`:
+first {ref}``install the `myst-parser` Python package <myst-parser:intro.md#installation>``
+and then {ref}`enable it on your configuration <myst-parser:intro.md#enable-myst-in-sphinx>`:
 
 ```{code-block} py
 :caption: conf.py