Add sphinx-hoverxref example page

Author: benjaoming

docs/_config.yml

@@ -1,5 +1,6 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
+# Comprehensive example: https://github.com/executablebooks/jupyter-book/blob/master/docs/_config.yml
 
 title: Example Jupyter Book for Read the Docs
 author: Read the Docs team
@@ -30,3 +31,31 @@ repository:
 html:
   use_issues_button: true
   use_repository_button: true
+
+sphinx:
+  config:
+    intersphinx_mapping:
+      ebp:
+        - "https://executablebooks.org/en/latest/"
+        - null
+      myst-parser:
+        - "https://myst-parser.readthedocs.io/en/latest/"
+        - null
+      myst-nb:
+        - "https://myst-nb.readthedocs.io/en/latest/"
+        - null
+      sphinx:
+        - "https://www.sphinx-doc.org/en/master"
+        - null
+      nbformat:
+        - "https://nbformat.readthedocs.io/en/latest"
+        - null
+      sd:
+        - https://sphinx-design.readthedocs.io/en/latest
+        - null
+
+  extra_extensions:
+    - sphinx_inline_tabs
+    - sphinx_proof
+    - sphinx_examples
+    - hoverxref.extension

docs/_toc.yml

@@ -7,3 +7,4 @@ chapters:
 - file: markdown
 - file: notebooks
 - file: markdown-notebooks
+- file: sphinx-hoverxref

docs/intro.md

@@ -1,8 +1,38 @@
+(intro)=
+
 # Jupyter Book on Read the Docs
 
-This example shows a Jupyter Book project built and published on Read the Docs. You're encouraged to view it to get inspiration and copy & paste from the files in [the source code][github]. If you are using Read the Docs for the first time, have a look at the official [Read the Docs Tutorial][tutorial]. If you are using Jupyter Book for the first time, have a look at the [official Jupyter Book documentation][jb-docs].
+This example shows a Jupyter Book project built and published on Read the Docs.
+You're encouraged to view it to get inspiration and copy & paste from the files in [the source code repository][github], where you will also find the relevant configuration for building Jupyter Book projects on Read the Docs.
+If you are using Read the Docs for the first time, have a look at the official [Read the Docs Tutorial][tutorial].
+If you are using Jupyter Book for the first time, have a look at the [official Jupyter Book documentation][jb-docs].
+
+## Why run Jupyter Book with Read the Docs?
+
+[Read the Docs](https://readthedocs.org/) simplifies developing Jupyter Book projects by automating building, versioning, and hosting of your project for you.
+You might be familiar with Read the Docs for software documentation projects, but these features are just as relevant for science.  
+
+With Read the Docs, you can improve collaboration on your Jupyter Book project with Git (GitHub, GitLab, BitBucket etc.) and then connect the Git repository to Read the Docs.
+Once Read the Docs and the git repository are connected, your project will be built and published automatically every time you commit and push changes with git.
+Furthermore, if you open Pull Requests, you can preview the result as rendered by Jupyter Book.
+
+## What is in this example?
+
+Jupyter Book has a number of built-in features, which you can see examples of here:
+
+* [Examples of Markdown](/markdown)
+* [Rendering a notebook Jupyter Notebook](/notebooks)
+* [A notebook written in MyST Markdown](/markdown-notebooks)
+
+We have also added some popular features for Jupyter Book that really you shouldn't miss when building your own project:
+
+* [intersphinx to link to other documentation and Jupyter Book projects](/sphinx-hoverxref)
+* [sphinx-examples to show examples and results side-by-side](/sphinx-hoverxref)
+* [sphinx-hoverxref to preview cross-references](/sphinx-hoverxref)
+* [sphinx-proof for logic and math, to write proofs, theorems, lemmas etc.](/sphinx-hoverxref)
+* [sphinx-inline-tabs to display alternatives side-by-side with a tabbed interface](/sphinx-hoverxref)
 
-# Jupyter Book examples
+## Jupyter Book examples
 
 This is a small sample book to give you a feel for how book content is
 structured.

docs/requirements.txt

@@ -1,3 +1,7 @@
 jupyter-book
 matplotlib
 numpy
+sphinx-inline-tabs
+sphinx-examples
+sphinx-proof
+sphinx-hoverxref

docs/sphinx-hoverxref.md

@@ -0,0 +1,28 @@
+# sphinx-hoverxref - preview cross-references
+
+Using sphinx-hoverxref, we can preview cross-references in the documentation.
+
+For instance, try placing your mouse over {hoverxref}`this reference to the front page <intro>`.
+We have used a named "target" for the reference. Here are some examples of how to name your targets:
+
+```{tab} reStructuredText
+
+```rest
+.. _foobar:
+
+My Headline
+===========
+
+Here is a paragraph, we link to this headline :hoverxref:`like this <foobar>`
+```
+
+```{tab} MyST
+
+```markdown
+
+ (foobar)=
+ 
+ # My Headline
+ 
+ Here is a paragraph, we link to this headline {hoverxref}`like this <foobar>`.
+```