Port to PyData-Sphinx Theme (#256)

* start port to pydata-sphinx theme * add theme to extensions in conf file * add pydata-sphinx-theme to requirements * modifying docs structure for correct layout of headings
jupyter · Aug 22, 2023 · 70e6b3f · 70e6b3f
1 parent addf6de
commit 70e6b3f
Show file tree

Hide file tree

Showing 33 changed files with 157 additions and 65 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,5 +1,6 @@
-Contributing to the Jupyter NbClassic
-=====================================
+=================================
+Contributing to Jupyter NbClassic
+=================================
 
 If you're reading this section, you're probably interested in contributing to
 Jupyter.  Welcome and thanks for your interest in contributing!

diff --git a/docs/autogen_config.py b/docs/autogen_config.py
@@ -6,7 +6,7 @@
 header = """\
 .. _config:
 
-
+====================================
 Config file and command line options
 ====================================
 

diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt
@@ -1,5 +1,6 @@
 sphinx>=1.3.6
 sphinx-rtd-theme
+pydata-sphinx-theme
 nbsphinx
 sphinxcontrib_github_alt
 myst_parser

diff --git a/docs/source/_templates/sidebar-nav-bs-index.html b/docs/source/_templates/sidebar-nav-bs-index.html
@@ -0,0 +1,24 @@
+<style>
+    #bd-docs-nav .toctree-toggle,
+    #bd-docs-nav .toctree-checkbox {
+      display: none;
+    }
+    #bd-docs-nav .toctree-l1 > a{
+      font-weight: bold;
+    }
+  </style>
+
+  <nav class="bd-links" id="bd-docs-nav" aria-label="{{ _('Documentation Contents') }}">
+    <div class="bd-toc-item navbar-nav">
+      <!-- Specify a startdepth of 0 instead of default of 1 -->
+      {{ generate_toctree_html(
+        "sidebar",
+        startdepth=0,
+        show_nav_level=4,
+        maxdepth=4,
+        collapse=True,
+        includehidden=True,
+        titles_only=True
+      ) }}
+    </div>
+  </nav>
diff --git a/docs/source/comms.rst b/docs/source/comms.rst
@@ -1,3 +1,4 @@
+=====
 Comms
 =====
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -161,12 +161,37 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/nbclassic",
+            "icon": "fa-solid fa-box",
+        }
+    ],
+    "use_edit_page_button": True,
+    "github_url": "https://github.com/jupyter/nbclassic",
+    "navbar_end": [
+        # disabled until widget dark variables are available
+        # "theme-switcher",
+        "navbar-icon-links",
+    ],
+    "secondary_sidebar_items": ["edit-this-page", "sourcelink", "search-field.html"]
+}
+
+html_context = {
+    # disabled until widget dark variables are available
+    "default_mode": "light",
+    "doc_path": "docs",
+    "github_repo": "nbclassic",
+    "github_user": "jupyter",
+    "github_version": "main",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -209,7 +234,9 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    "**": ["sidebar-nav-bs-index.html"]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

diff --git a/docs/source/config_docs.rst b/docs/source/config_docs.rst
@@ -0,0 +1,15 @@
+=============
+Configuration
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Configuration
+
+   config_overview
+   config
+   public_server
+   security
+   frontend_config
+   examples/Notebook/Distributing Jupyter Extensions as Python Packages
+   extending/index.rst
diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst
@@ -1,5 +1,4 @@
-.. _configuration-overview:
-
+======================
 Configuration Overview
 ======================
 
@@ -51,7 +50,7 @@ front-end NbClassic client (i.e. the familiar notebook interface).
 
       :ref:`Command line arguments for configuration <config>` settings are documented in the configuration file and the user documentation.
 
-  - :ref:`Running a Notebook server <working_remotely>`
+  - Review the section: :ref:`Running a Notebook server <working_remotely>`
   - Related: `Configuring a language kernel <https://ipython.readthedocs.io/en/latest/install/kernel_install.html>`_
     to run in the Notebook server enables your server to run other languages, like R or Julia.
 

diff --git a/docs/source/contribute_docs.rst b/docs/source/contribute_docs.rst
@@ -0,0 +1,17 @@
+==========
+Contribute
+==========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contributor Documentation
+
+   contributing
+   nbclassic_dev_faq
+   development_faq
+
+.. toctree::
+    :hidden:
+
+    examples/Notebook/nbpackage/mynotebook.ipynb
+    examples/Notebook/nbpackage/nbs/other.ipynb
diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst
@@ -1,5 +1,3 @@
-.. _development_faq:
-
 Developer FAQ
 =============
 

diff --git a/docs/source/examples/Notebook/Connecting with the Qt Console.ipynb b/docs/source/examples/Notebook/Connecting with the Qt Console.ipynb
@@ -104,9 +104,6 @@
   }
  ],
  "metadata": {
-  "nbsphinx": {
-   "execute": "never"
-  },
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
@@ -123,6 +120,9 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.5.2"
+  },
+  "nbsphinx": {
+   "execute": "never"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb b/docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb
@@ -131,9 +131,6 @@
   }
  ],
  "metadata": {
-  "nbsphinx": {
-   "execute": "never"
-  },
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
@@ -150,6 +147,9 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.5.2"
+  },
+  "nbsphinx": {
+   "execute": "never"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb b/docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb
@@ -507,4 +507,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}
diff --git a/docs/source/examples/Notebook/Importing Notebooks.ipynb b/docs/source/examples/Notebook/Importing Notebooks.ipynb
@@ -511,9 +511,6 @@
  ],
  "metadata": {
   "gist_id": "6011986",
-  "nbsphinx": {
-   "execute": "never"
-  },
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
@@ -530,6 +527,9 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.5.1+"
+  },
+  "nbsphinx": {
+   "execute": "never"
   }
  },
  "nbformat": 4,

diff --git a/docs/source/examples/Notebook/examples_index.rst b/docs/source/examples/Notebook/examples_index.rst
@@ -9,7 +9,7 @@ __ https://nbviewer.jupyter.org/github/jupyter/nbclassic/blob/main/
    docs/source/examples/Notebook/
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    What is the Jupyter Notebook
    Notebook Basics

diff --git a/docs/source/examples/Notebook/nbpackage/nbs/other.ipynb b/docs/source/examples/Notebook/nbpackage/nbs/other.ipynb
@@ -5,7 +5,6 @@
    "metadata": {},
    "source": [
     "### Other notebook\n",
-    "\n",
     "This notebook just defines `bar`"
    ]
   },

diff --git a/docs/source/extending/bundler_extensions.rst b/docs/source/extending/bundler_extensions.rst
@@ -1,3 +1,4 @@
+=========================
 Custom bundler extensions
 =========================
 

diff --git a/docs/source/extending/contents.rst b/docs/source/extending/contents.rst
@@ -1,5 +1,4 @@
-.. _contents_api:
-
+============
 Contents API
 ============
 

diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst
@@ -1,3 +1,4 @@
+===========================
 Custom front-end extensions
 ===========================
 

diff --git a/docs/source/extending/handlers.rst b/docs/source/extending/handlers.rst
@@ -1,3 +1,4 @@
+=======================
 Custom request handlers
 =======================
 

diff --git a/docs/source/extending/keymaps.rst b/docs/source/extending/keymaps.rst
@@ -1,3 +1,4 @@
+=================
 Customize keymaps
 =================
 

diff --git a/docs/source/extending/savehooks.rst b/docs/source/extending/savehooks.rst
@@ -1,3 +1,4 @@
+===============
 File save hooks
 ===============
 

diff --git a/docs/source/frontend_config.rst b/docs/source/frontend_config.rst
@@ -1,7 +1,6 @@
-.. _frontend_config:
-
+==================================
 Configuring the NbClassic frontend
-=================================
+==================================
 
 .. note::
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,38 +6,24 @@ Jupyter NbClassic
 
 .. toctree::
    :maxdepth: 1
-   :caption: User Documentation
+   :titlesonly:
 
-   nbclassic
-   notebook
-   ui_components
-   examples/Notebook/examples_index.rst
-   troubleshooting
-   changelog
-   comms
+   user_docs
+
+Information about using and troubleshooting NbClassic as well as examples and changes throughout the history of the project.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Configuration
+   :titlesonly:
+
+   config_docs
 
-   config_overview
-   config
-   public_server
-   security
-   frontend_config
-   examples/Notebook/Distributing Jupyter Extensions as Python Packages
-   extending/index.rst
+Find out more about configuring NbClassic.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contributor Documentation
+   :titlesonly:
 
-   contributing
-   nbclassic_dev_faq
-   development_faq
-
-.. toctree::
-    :hidden:
+   contribute_docs      
 
-    examples/Notebook/nbpackage/mynotebook.ipynb
-    examples/Notebook/nbpackage/nbs/other.ipynb
+Additional information about contributing to and developing NbClassic.
diff --git a/docs/source/nbclassic.rst b/docs/source/nbclassic.rst
@@ -1,8 +1,11 @@
-.. _htmlnotebook:
+:html_theme.sidebar_secondary.remove:
 
+=================
 Jupyter NbClassic
-====================
-
+=================
+.. toctree::
+   :maxdepth: 2
+
 Introduction
 ------------
 
@@ -34,14 +37,14 @@ Installation
 ~~~~~~~~~~~~
 
 Installing from PyPI:
-``> pip install nbclassic``
+``pip install nbclassic``
 This will automatically enable the extension in Jupyter Server.
 
 Launch directly:
-``> jupyter nbclassic``
+``jupyter nbclassic``
 
 Alternatively, you can run Jupyter Server and visit the `/tree` endpoint:
-``> jupyter server``
+``jupyter server``
 
 Configuration
 ~~~~~~~~~~~~~

diff --git a/docs/source/nbclassic_dev_faq.rst b/docs/source/nbclassic_dev_faq.rst
@@ -1,3 +1,4 @@
+============================
 The Development of NbClassic
 ============================
 

diff --git a/docs/source/notebook.rst b/docs/source/notebook.rst
@@ -1,5 +1,4 @@
-.. _htmlnotebook:
-
+====================
 The Jupyter Notebook
 ====================
 

diff --git a/docs/source/public_server.rst b/docs/source/public_server.rst
@@ -1,5 +1,6 @@
 .. _working_remotely:
 
+=======================================
 Running a Jupyter Server with NbClassic
 =======================================
-Original file line number
+Diff line change
@@ -1,3 +1,4 @@
+    =====
     Comms
     =====
@@ Expand Down @@