From 8f5c1503e80218d6e4a4f3f0c4584bc3d788c863 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 23 Nov 2022 13:32:18 +0100 Subject: [PATCH] Update Binder docs and design --- README.md | 4 +-- doc/_data/scripts/gen_federation_md.py | 6 ++--- doc/_data/scripts/gen_support_md.py | 4 +-- doc/about/federation.md | 1 + doc/about/team.md | 2 +- doc/conf.py | 25 ++++++++++++++---- noxfile.py | 35 +++++++++++++------------- 7 files changed, 47 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index ccf758b..fdb8917 100644 --- a/README.md +++ b/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: diff --git a/doc/_data/scripts/gen_federation_md.py b/doc/_data/scripts/gen_federation_md.py index 81d05d7..618399d 100644 --- a/doc/_data/scripts/gen_federation_md.py +++ b/doc/_data/scripts/gen_federation_md.py @@ -8,9 +8,9 @@ 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} @@ -18,7 +18,7 @@ ^^^ - + ``` """ diff --git a/doc/_data/scripts/gen_support_md.py b/doc/_data/scripts/gen_support_md.py index 297ed32..ba0b1ca 100644 --- a/doc/_data/scripts/gen_support_md.py +++ b/doc/_data/scripts/gen_support_md.py @@ -25,7 +25,7 @@ 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 @@ -33,7 +33,7 @@ **{supporter["name"]}** ^^^ - + ``` diff --git a/doc/about/federation.md b/doc/about/federation.md index 312a2ed..0d42690 100644 --- a/doc/about/federation.md +++ b/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 ``` diff --git a/doc/about/team.md b/doc/about/team.md index dae28a6..3f3bf46 100644 --- a/doc/about/team.md +++ b/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 `. +The Binder Team is a subset of the {external:tc:ref}`JupyterHub Core 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 diff --git a/doc/conf.py b/doc/conf.py index 456c5e4..b1cb10c 100644 --- a/doc/conf.py +++ b/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 = { diff --git a/noxfile.py b/noxfile.py index a22c03e..b2bcdad 100644 --- a/noxfile.py +++ b/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)