Merge pull request #267 from choldgraf/theme-update

Update configuration for PyData Sphinx Theme
jupyterhub · Nov 7, 2022 · 21072dc · 21072dc
2 parents 34144e4 + 59464b3
commit 21072dc
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -23,3 +23,28 @@ Binder is maintained by the [Binder team](https://github.com/jupyterhub/team-com
 
 
 The JupyterHub team also maintains analysis of binder data including [billing data](https://github.com/jupyterhub/binder-billing) and [activity data](https://github.com/jupyterhub/binder-data).
+
+## Build the documentation
+
+This documentation is built with [the Sphinx Documentation engine]().
+The easiest way to build the documentation is with [the tool `nox`](https://nox.thea.codes/en/stable/).
+`nox` is kind-of like a Makefile, it is a way to automatically install environments and run commands locally.
+To build this documentation with `nox`, run:
+
+```bash
+pip install nox
+nox -s docs
+```
+
+or to launch a live server that re-builds and re-loads pages as you save files:
+
+```bash
+nox -s docs-live
+```
+
+Alternatively, you may build the documentation directly with Sphinx:
+
+```bash
+pip install -r doc/doc-requirements.txt
+sphinx-build -b html doc doc/_build
+```
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
@@ -41,10 +41,14 @@ div.sphinxsidebarwrapper ul {
 /* Badges on front page */
 div.badges img {
     float: left;
-    padding-right: .5em;
+    margin-right: .5em;
 }
 
 /* Logo */
-img.logo{
-    padding: 0.2em;
+img.logo__image {
+    padding: 0.25rem;
+}
+
+p.logo__title {
+    font-size: 1.25em;
 }
diff --git a/doc/_static/images/logo-dark.png b/doc/_static/images/logo-dark.png
diff --git a/doc/_static/images/logo.png b/doc/_static/images/logo.png
diff --git a/doc/conf.py b/doc/conf.py
@@ -1,20 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-import os
-import os.path as op
-from pathlib import Path
-import requests
-
 # -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx_copybutton",
     "myst_parser",
@@ -32,18 +19,12 @@
 source_suffix = [".rst", ".md"]
 
 # The master toctree document.
-master_doc = "index"
+main_doc = "index"
 
 # General information about the project.
 project = "Binder"
-copyright = "2017, The Binder Team"
+copyright = "2022, The Binder Team"
 author = "The Binder Team"
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
 version = "0.1b"
 # The full version, including alpha/beta/rc tags.
 release = "0.1b"
@@ -52,35 +33,12 @@
     "r2d": ("https://repo2docker.readthedocs.io/en/latest/", None),
     "tc": ("https://jupyterhub-team-compass.readthedocs.io/en/latest/", None),
 }
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-# Binder Logo
-html_logo = "_static/images/logo.png"
-html_favicon = "_static/images/favicon.png"
-
 # -- 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 = "pydata_sphinx_theme"
+html_favicon = "_static/images/favicon.png"
 
 # 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
@@ -98,8 +56,13 @@
             "icon": "_static/favicon.png",
             "type": "local",
         }
-   ],
-   "navbar_end": ["navbar-icon-links", "support-button"],
+    ],
+    "navbar_align": "left",
+    "navbar_end": ["theme-switcher", "navbar-icon-links", "support-button"],
+    "logo": {
+        "image_light": "images/logo.png",
+        "image_dark": "images/logo-dark.png",
+    }
 }
 
 html_context = {
@@ -113,10 +76,6 @@
 html_sidebars = {
     "index": [],  # Remove sidebars on landing page to save space
 }
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 
@@ -141,60 +100,6 @@
     "deflist",
 ]
 
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "Binderdoc"
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "Binder.tex", "Binder Documentation", "The Binder Team", "manual"),
-]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "binder", "Binder Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "Binder",
-        "Binder Documentation",
-        author,
-        "Binder",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
-
 # -- Scripts --------------------------------------------------------------
 from subprocess import run
 import shlex

diff --git a/doc/index.md b/doc/index.md
@@ -1,3 +1,6 @@
+---
+theme_html_remove_secondary_sidebar:
+---
 (binder-docs)=
 # Binder Documentation
 

diff --git a/noxfile.py b/noxfile.py
@@ -0,0 +1,28 @@
+"""A nox configuration file so that we can build the documentation easily with nox.
+- see the README.md for information about nox.
+- ref: https://nox.thea.codes/en/stable/
+"""
+import nox
+from pathlib import Path
+
+nox.options.reuse_existing_virtualenvs = True
+
+
+@nox.session
+def docs(session):
+    session.install("-r", "doc/doc-requirements.txt")
+    session.run("sphinx-build", "-b=html", "doc/", "doc/_build/html")
+
+
+@nox.session(name="docs-live")
+def docs_live(session):
+    session.install("-r", "doc/doc-requirements.txt")
+    session.install("sphinx-autobuild")
+    session.run(
+        "sphinx-autobuild",
+        "--re-ignore",
+        "doc/_data*",
+        "-b=html",
+        "doc/",
+        "doc/_build/html",
+    )