Merge pull request #271 from choldgraf/docs-update-2

Some minor updates to the Binder docs and design fixes

Author: consideRatio

README.md

@@ -1,4 +1,4 @@
-# binder
+# `mybinder.org` user documentation
 
 [![Documentation Status](https://readthedocs.org/projects/mybinder/badge/?version=latest)](https://mybinder.readthedocs.io/en/latest/?badge=latest)
 [![Join the chat at https://gitter.im/jupyterhub/binder](https://badges.gitter.im/jupyterhub/binder.svg)](https://gitter.im/jupyterhub/binder?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
@@ -39,7 +39,7 @@ 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
+nox -s docs -- live
 ```
 
 Alternatively, you may build the documentation directly with Sphinx:

doc/_data/scripts/gen_federation_md.py

@@ -8,17 +8,17 @@
 template_binderhub = """
 ```{{grid-item-card}}
 :text-align: center
-:class-header: bg-light
+:class-header: sd-text-dark
 :class-body: sd-p-4 sd-m-auto
-:class-footer: bg-light
+:class-card: bg-light
 :text-align: center
 :link: {URL_BINDERHUB}
 
 **{BINDERHUB_SUBDOMAIN}**
 
 ^^^
 
-<img src="{LOGO}" style="max-height: 5em; min-height: 2em;" />
+<img src="{LOGO}" class="dark-light" style="max-height: 5em; min-height: 2em;" />
 ```
 
 """

doc/_data/scripts/gen_support_md.py

@@ -25,15 +25,15 @@
       output += dedent(f"""
       ```{{grid-item-card}}
       :text-align: center
-      :class-header: bg-light
+      :class-card: bg-light
       :class-body: sd-p-4 d-flex sd-m-auto
       :link: {supporter["url"]}
       :text-align: center
 
       **{supporter["name"]}**
       ^^^
 
-      <img src="{supporter['logo']}" style="max-height:5em;min-height:2em;" />
+      <img src="{supporter['logo']}" class="dark-light" style="max-height:5em;min-height:2em;" />
       
       ```
 

doc/about/federation.md

@@ -19,6 +19,7 @@ federation, check out [](federation/joining).
 
 Below is a list of the current member hubs in the BinderHub Federation:
 
+% generate with doc/_data/scripts/gen_federation_md.py
 ```{include} /_data/snippets/federation_md.txt
 ```
 

doc/about/team.md

@@ -5,7 +5,7 @@ This page contains basic information about the people and tools behind the Binde
 (team:members)=
 ## The Binder Team
 
-The Binder Team is a subset of the {external+tc:doc}`JupyterHub Core Team <team>`.
+The Binder Team is a subset of the {external:tc:ref}`JupyterHub Core Team <jupyterhub-team>`.
 This group builds and maintains our open source projects, operates the cloud infrastructure at mybinder.org, and broadly supports the mission of the Binder project for the communities we serve.
 
 The service at `mybinder.org` is powered by a collection of BinderHub

doc/conf.py

@@ -46,23 +46,38 @@
 #
 html_theme_options = {
     "use_edit_page_button": True,
-    "google_analytics_id": "UA-101904940-3",
-    "github_url": "https://github.com/jupyterhub/binder",
-    "twitter_url": "https://twitter.com/mybinderteam",
+    "analytics": {
+        "google_analytics_id": "UA-101904940-3",
+    },
     "icon_links": [
         {
             "name": "Go to mybinder.org",
             "url": "https://mybinder.org",
             "icon": "_static/favicon.png",
             "type": "local",
-        }
+        },
+        {
+            "name": "GitHub repository",
+            "url": "https://github.com/jupyterhub/binder",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Twitter account",
+            "url": "https://twitter.com/mybinderteam",
+            "icon": "fa-brands fa-twitter",
+        },
+        {
+            "name": "Community Forum",
+            "url": "https://discourse.jupyter.org/c/binder/12",
+            "icon": "fa-brands fa-discourse",
+        },
     ],
     "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 = {

noxfile.py

@@ -3,26 +3,27 @@
 - ref: https://nox.thea.codes/en/stable/
 """
 import nox
-from pathlib import Path
 
 nox.options.reuse_existing_virtualenvs = True
 
+build_command = ["-b", "html", "doc", "doc/_build/html"]
 
-@nox.session
+@nox.session(python="3.9")
 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",
-    )
+    if "live" in session.posargs:
+        AUTOBUILD_IGNORE = [
+            "*/.github/*",
+            "*/_data/*",
+            "*/howto/languages.rst",
+            "*/howto/user_interface.rst",
+            "*/howto/lab_workspaces.rst",
+            "*/using/config_files.rst",
+        ]
+        cmd = ["sphinx-autobuild"]
+        for folder in AUTOBUILD_IGNORE:
+            cmd.extend(["--ignore", f"*/{folder}/*"])
+        cmd.extend(build_command)
+        session.run(*cmd)
+    else:
+        session.run("sphinx-build", *build_command)