Switch docs site to pydata-sphinx-theme (#368)

- Change html_theme from quantecon_book_theme to pydata_sphinx_theme
- Update html_theme_options for pydata compatibility (github icon, PyPI link, edit button)
- Add html_context for GitHub edit links
- Remove sphinx_thebe extension (theme-specific)
- Remove templates_path (no _templates dir exists)
- Add pydata-sphinx-theme>=0.15 to [doc] dependencies
- Remove sphinx-thebe from [doc] dependencies
- Convert {margin} directives to {tip}/{admonition} (margin is sphinx-book-theme specific)
- Remove GitHub external link from toctree (now shown as header icon)

Author: mmcky

docs/conf.py

@@ -16,15 +16,11 @@
     "sphinx_copybutton",
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
-    "sphinx_thebe",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -43,12 +39,12 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "quantecon_book_theme"
+# The theme to use for HTML and HTML Help pages.
+# We use pydata-sphinx-theme for the documentation site itself, while
+# quantecon_book_theme is the theme being documented.
+html_theme = "pydata_sphinx_theme"
 html_logo = "_static/qe-logo.png"
-html_title = "Quantecon Book Theme"
+html_title = "QuantEcon Book Theme"
 html_copy_source = True
 html_sourcelink_suffix = ""
 html_favicon = "_static/qe-logo.png"
@@ -62,37 +58,28 @@
 # -- Togglebutton configuration ----------------------------------------------
 togglebutton_hint = "Show"
 togglebutton_hint_hide = "Hide"
-thebe_config = {
-    "repository_url": "https://github.com/binder-examples/jupyter-stacks-datascience",
-    "repository_branch": "master",
-}
 
 html_theme_options = {
-    "path_to_docs": "docs",
-    "repository_url": "https://github.com/QuantEcon/quantecon-book-theme",
-    # "repository_branch": "gh-pages",  # For testing
-    "launch_buttons": {
-        "binderhub_url": "https://mybinder.org",
-        # "jupyterhub_url": "https://datahub.berkeley.edu",  # For testing
-        "colab_url": "https://colab.research.google.com/",
-        "notebook_interface": "jupyterlab",
-        "thebe": True,
-    },
+    "github_url": "https://github.com/QuantEcon/quantecon-book-theme",
     "use_edit_page_button": True,
-    "use_issues_button": True,
-    "use_repository_button": True,
-    "expand_sections": ["reference/index"],
-    # For testing
-    # "home_page_in_toc": True,
-    # "single_page": True
-    # "extra_footer": "<a href='https://google.com'>Test</a>",
-    # "extra_navbar": "<a href='https://google.com'>Test</a>",
-    # Uncomment to test Pygments built-in styles:
-    # "qetheme_code_style": False,
+    "show_prev_next": True,
+    "navigation_with_keys": False,
+    "header_links_before_dropdown": 6,
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/quantecon-book-theme/",
+            "icon": "fas fa-box",
+        },
+    ],
 }
 
-# Uncomment to test different Pygments styles:
-# pygments_style = "monokai"
+html_context = {
+    "github_user": "QuantEcon",
+    "github_repo": "quantecon-book-theme",
+    "github_version": "main",
+    "doc_path": "docs",
+}
 
 bibtex_bibfiles = ["references.bib"]
 bibtex_reference_style = "author_year"

docs/index.md

@@ -57,7 +57,6 @@ developer/index
 
 reference/index
 api/index
-GitHub Repository <https://github.com/QuantEcon/quantecon-book-theme>
 ```
 
 ## Acknowledgements

docs/reference/markdown_limits.md

@@ -219,15 +219,17 @@ Link to above: {eq}`my_label2`
 
 Margin content can include all kinds of things, such as code blocks:
 
-````{margin} Code blocks in margins
+````{admonition} Margin example — Code blocks
+:class: tip
 ```python
 print("here is some python")
 ```
 ````
 
 as well as admonitions and images:
 
-````{margin} **Notes in margins**
+````{admonition} Margin example — Notes
+:class: tip
 ```{note}
 Wow, a note with an image in a margin!
 ![](../images/cool.jpg)
@@ -237,7 +239,7 @@ Wow, a note with an image in a margin!
 
 Here's some margin content, let's see how it interacts w/ the toggle button
 
-```{margin} My margin
+```{tip} Margin content
 Here's my margin content
 ```
 

docs/user/launch.md

@@ -22,7 +22,7 @@ html_theme_options = {
 }
 ```
 
-```{margin} Paired ipynb files
+```{tip} Paired ipynb files
 If you're using [Jupytext](https://jupytext.readthedocs.io/en/latest/) to
 pair an ipynb file with your text files, and that ipynb file is in the same
 folder as your content, then Binder/JupyterHub links will point to the ipynb

docs/user/layout.md

@@ -27,8 +27,11 @@ Here is my margin content, it is pretty cool!
 ```
 ````
 
-```{margin} **Here is my margin content**
-It is pretty cool!
+```{admonition} Margin example
+:class: tip
+In the quantecon-book-theme, this pops out to the right margin:
+
+**Here is my margin content** — It is pretty cool!
 ```
 
 ### Content sidebars
@@ -55,7 +58,9 @@ Here is my sidebar content, it is pretty cool!
 
 Sidebar/margin content supports code blocks:
 
-````{margin} Code blocks in margins
+````{admonition} Margin example — Code blocks
+:class: tip
+In the theme, this renders as a code block in the right margin:
 ```python
 print("here is some python")
 ```
@@ -71,7 +76,9 @@ print("here is some python")
 
 As well as admonitions and images:
 
-````{margin} **Notes in margins**
+````{admonition} Margin example — Notes
+:class: tip
+In the theme, this renders as a note in the right margin:
 ```{note}
 Wow, a note with an image in a margin!
 ![](../images/cool.jpg)
@@ -132,7 +139,7 @@ This content will be full-width
 This content will be full-width
 ```
 
-```{margin} A note for ipynb users
+```{tip} A note for ipynb users
 If you are using a Jupyter Notebook as inputs to your documentation using the
 [MyST-NB extension](https://myst-nb.readthedocs.io/en/latest/), you can trigger
 this behavior with a code cell by adding a `full-width` tag to the cell.

docs/user/notebooks.md

@@ -102,7 +102,7 @@ ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'])
 ax.set(title="Smoother lines");
 ```
 
-```{margin} You can also pop out content to the margin
+```{tip} You can also pop out content to the margin
 For more information on how to do this,
 check out {doc}`layout`.
 ```

pyproject.toml

@@ -52,6 +52,7 @@ code_style = [
     "pre-commit"
 ]
 doc = [
+    "pydata-sphinx-theme>=0.15",
     "folium",
     "numpy",
     "matplotlib",
@@ -60,7 +61,6 @@ doc = [
     "nbclient",
     "myst-nb",
     "sphinx-togglebutton>=0.2.1",
-    "sphinx-thebe",
     "sphinx-copybutton",
     "docutils>=0.20",
     "plotly",