Add sphinx-examples

Author: benjaoming

docs/_toc.yml

@@ -7,5 +7,6 @@ chapters:
 - file: markdown
 - file: notebooks
 - file: markdown-notebooks
-- file: sphinx-hoverxref
 - file: intersphinx
+- file: sphinx-hoverxref
+- file: sphinx-examples

docs/intro.md

@@ -3,15 +3,15 @@
 # Jupyter Book on Read the Docs
 
 This example shows a Jupyter Book project built and published on Read the Docs.
-You're encouraged to use it to get inspiration and copy & paste from the files in [the source code repository][github]. In the source repository you will also find the relevant configuration and instructions for building Jupyter Book projects on Read the Docs.
+You're encouraged to use it to get inspiration and copy & paste from the files in [the source code repository][github]. In the source repository, you will also find the relevant configuration and instructions 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.  
+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.
@@ -31,7 +31,7 @@ It does not go in-depth into any particular topic - check out [the Jupyter Book
 We have also added some popular features for Jupyter Book that really you shouldn't miss when building your own project with Jupyter Book and Read the Docs:
 
 * [intersphinx to link to other documentation and Jupyter Book projects](/intersphinx)
-* [sphinx-examples to show examples and results side-by-side](/sphinx-hoverxref) (TODO)
+* [sphinx-examples to show examples and results side-by-side](/sphinx-examples)
 * [sphinx-hoverxref to preview cross-references](/sphinx-hoverxref)
 * [sphinx-proof for logic and math, to write proofs, theorems, lemmas etc.](/sphinx-hoverxref) (TODO)
 * [sphinx-inline-tabs to display alternatives side-by-side with a tabbed interface](/sphinx-hoverxref) (TODO)

docs/sphinx-examples.md

@@ -0,0 +1,11 @@
+# Examples boxes with sphinx-examples
+
+In this example project, we have enabled the extension `sphinx-examples` in `_config.yml` to be able to display source code alongside its rendered result.
+
+You can use it this way:
+
+```{example} Use examples to show source code and rendered result
+```{example} Example title
+Here's my **example**!
+```
+