Merge branch 'bootstrap' of github.com:readthedocs-examples/example-jupyter-book into bootstrap

Author: benjaoming

docs/_config.yml

@@ -51,11 +51,25 @@ sphinx:
         - "https://nbformat.readthedocs.io/en/latest"
         - null
       sd:
-        - https://sphinx-design.readthedocs.io/en/latest
+        - "https://sphinx-design.readthedocs.io/en/latest"
         - null
-
+      sphinxproof:
+        - "https://sphinx-proof.readthedocs.io/en/latest/"
+        - null
+    hoverxref_intersphinx:
+     - "sphinxproof"
+    mathjax3_config:
+      tex:
+        macros:
+          "N": "\\mathbb{N}"
+          "floor": ["\\lfloor#1\\rfloor", 1]
+          "bmat": ["\\left[\\begin{array}"]
+          "emat": ["\\end{array}\\right]"]
+        
   extra_extensions:
+    - sphinx.ext.intersphinx
     - sphinx_inline_tabs
     - sphinx_proof
     - sphinx_examples
-    - hoverxref.extension
+    - hoverxref.extension
+

docs/_toc.yml

@@ -3,8 +3,16 @@
 
 format: jb-book
 root: intro
-chapters:
-- file: markdown
-- file: notebooks
-- file: markdown-notebooks
-- file: sphinx-hoverxref
+parts:
+- caption: Basic examples 🪄
+  chapters:
+  - file: markdown
+  - file: notebooks
+  - file: markdown-notebooks
+- caption: Cool extensions 🕶️
+  chapters:
+  - file: intersphinx
+  - file: sphinx-examples
+  - file: sphinx-hoverxref
+  - file: sphinx-proof
+

docs/intersphinx.md

@@ -0,0 +1,28 @@
+# Intersphinx
+
+Behind the built-in Sphinx extension `intersphinx` is a powerful tool to reference sections in other Sphinx and Jupyter Book documentation projects.
+
+You can configure mappings to external Sphinx projects in your Jupyter Book configuration, the `_config.yml` file. In this example project, we have configured `ebp` to reference `https://executablebooks.org/en/latest/`. In the following code examples, we refer to the configured `ebp` mapping and link directly to a section called `tools`.
+
+```{tab} MyST (Markdown)
+
+```{example}
+We can link to pages in other documentation projects.
+This is a link to the
+[Executable Book project's list of tools they build](ebp:tools)
+```
+
+
+```{tab} reStructuredText
+
+```{example}
+
+```{eval-rst}
+We can link to pages in other documentation projects.
+This is a link to the
+:doc:`Executable Book project's list of tools they build <ebp:tools>`
+```
+
+```{note}
+In the above `reStructuredText` example, we use `{eval-rst}` to write reST inside a `.md` file (i.e. the one you are reading now). You only need to use this directive if you are writing reST code in a `.md` file.
+```

docs/intro.md

@@ -3,43 +3,42 @@
 # 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 repository][github], where you will also find the relevant configuration 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.
 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:
+Jupyter Book has a number of built-in features.
+This is a small example book to give you a feel for how book content is structured.
+It shows off a few of the major file types, as well as some sample content.
+It does not go in-depth into any particular topic - check out [the Jupyter Book documentation][jb-docs] for more information.
 
 * [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:
+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](/sphinx-hoverxref)
-* [sphinx-examples to show examples and results side-by-side](/sphinx-hoverxref)
+* [intersphinx to link to other documentation and Jupyter Book projects](/intersphinx)
+* [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)
-* [sphinx-inline-tabs to display alternatives side-by-side with a tabbed interface](/sphinx-hoverxref)
+* [sphinx-proof for logic and math, to write proofs, theorems, lemmas etc.](/sphinx-proof)
 
-## Jupyter Book examples
 
-This is a small sample book to give you a feel for how book content is
-structured.
-It shows off a few of the major file types, as well as some sample content.
-It does not go in-depth into any particular topic - check out [the Jupyter Book documentation][jb-docs] for more information.
+## Table of Contents
 
-Check out the content pages bundled with this sample book to see more.
+Here is an automatically generated Tabel of Contents:
 
 ```{tableofcontents}
 ```

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**!
+```
+

docs/sphinx-proof.md

@@ -0,0 +1,24 @@
+# Write proofs with sphinx-proof
+
+Easily render proofs, theorems, axioms, lemmas, definitions and much more with `sphinx-proof`. Read more in the [documentation of sphinx-proof](sphinxproof:syntax).
+
+````{prf:proof}
+We'll omit the full proof.
+
+But we will prove sufficiency of the asserted conditions.
+
+To this end, let $y \in \mathbb R^n$ and let $S$ be a linear subspace of $\mathbb R^n$.
+
+Let $\hat y$ be a vector in $\mathbb R^n$ such that $\hat y \in S$ and $y - \hat y \perp S$.
+
+Let $z$ be any other point in $S$ and use the fact that $S$ is a linear subspace to deduce
+
+```{math}
+\| y - z \|^2
+= \| (y - \hat y) + (\hat y - z) \|^2
+= \| y - \hat y \|^2  + \| \hat y - z  \|^2
+```
+
+Hence $\| y - z \| \geq \| y - \hat y \|$, which completes the proof.
+````
+