jupyterhub · consideRatio · Nov 25, 2022 · Nov 23, 2022 · Nov 23, 2022 · Nov 24, 2022
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,3 +0,0 @@
-.contributor-grid .sd-card-text {
-    margin-bottom: 0;
-}

diff --git a/docs/building-blocks/index.rst b/docs/building-blocks/index.rst
@@ -1,8 +1,8 @@
 .. _blocks-index:
 
-========================
-Standard Building Blocks
-========================
+==================================
+Common workflows and helpful tools
+==================================
 
 With as many git repositories as we manage, it becomes useful to have a area for
 standardized building blocks. It allows us to optimize and gather knowledge

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,109 +1,32 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# Team Compass documentation build configuration file, created by
-# sphinx-quickstart on Sun Dec  3 20:44:20 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 
 # -- 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', "sphinx_design", 'sphinx.ext.mathjax', 'myst_parser']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-source_suffix = ['.rst']
-
-# The master toctree document.
-master_doc = 'index'
+extensions = ["sphinx_copybutton", "sphinx_design", "sphinx.ext.mathjax", "myst_parser"]
+templates_path = []
+source_suffix = [".rst", ".md"]
+root_doc = "index"
 
 # General information about the project.
-project = 'Team Compass'
-copyright = '2022, JupyterHub Team and Binder Team'
-author = 'JupyterHub Team and 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 = '1.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
-
-# 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
+project = "Team Compass"
+copyright = "2022, JupyterHub Team and Binder Team"
+author = "JupyterHub Team and Binder Team"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 def setup(app):
     app.add_css_file("custom.css")
 
 
 # -- 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'
-
-# Logo
-html_logo = '_static/logo.png'
-html_favicon = '_static/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
-# documentation.
-#
-# html_theme_options = {}
-
-# 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_theme = "pydata_sphinx_theme"
+html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.png"
+html_static_path = ["_static"]
 html_theme_options = {
     "use_edit_page_button": True,
-    "google_analytics_id": "UA-101904940-3",
+    "analytics": {
+        "google_analytics_id": "UA-101904940-3",
+    },
     "github_url": "https://github.com/jupyterhub/team-compass",
     "twitter_url": "https://twitter.com/projectjupyter",
     "icon_links": [
@@ -112,18 +35,19 @@ def setup(app):
             "url": "https://discourse.jupyter.org/c/jupyterhub/10",
             "icon": "fab fa-discourse",
         }
-   ],
-   "navbar_end": ["navbar-icon-links"],
+    ],
 }
 
 html_context = {
     "github_user": "jupyterhub",
     "github_repo": "team-compass",
-    "github_version": "master",
-    "doc_path": "doc",
+    "github_version": "main",
+    "doc_path": "docs",
     "source_suffix": source_suffix,
 }
 
 # -- Update contributor lists --------------------------------------------
+
 from subprocess import run
-run(['python', '_data/contributors/gen_contributors.py'], check=True)
+
+run(["python", "_data/contributors/gen_contributors.py"], check=True)
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
@@ -1,10 +1,12 @@
-# Contribute
+# New contributor guide
 
 Our project depends on contributions from volunteers across the world who are interested in supporting the JupyterHub Project.
 The sections below provide some resources to help you get started contributing to our community.
 
 ```{toctree}
+
 guide
 skills
 repository-info
-```
+../building-blocks/index
+```
diff --git a/docs/index-team_governance.rst b/docs/index-team_governance.rst
diff --git a/docs/index-team_guides.rst b/docs/index-team_guides.rst
@@ -1,17 +1,42 @@
 .. _guides_index:
 
-==============
-Team Resources
-==============
+================
+Team information
+================
 
 Resources and guides for team members to help us coordinate and work together more effectively.
 
+**Governance and structure** defines our decision-making policies, how we organize ourselves, and the practices that we commit to following.
+
+.. toctree:: 
+   :caption: Governance and structure
+   :maxdepth: 2
+
+   ../governance
+   ../binder/subdomains
+   ../team/structure
+   Jupyter Code of Conduct <https://jupyter.org/governance/conduct/code_of_conduct.html>
+
+
+**Team guides** describe our policy, process, and recommendations for day to day activities and operations.
+
 .. toctree::
+   :caption: Team guides
+   :maxdepth: 2
 
    team/member-guide
    team/repository-code-standards
-   team/adding-members
+   team/adding-members 
+   ../talking
+
+**Team coordination** is meant to share information and context across team members, and align us on a plan of action.
+
+.. toctree:: 
+   :caption: Team coordination
+   :maxdepth: 2
+
+   meetings/index
    team/shared-infrastructure
-   talking
-   building-blocks/index
+   team/binder-infrastructure
    team/community-strategy
+   ../milestones
diff --git a/docs/index.rst b/docs/index.rst
@@ -27,15 +27,13 @@ governance and planning.
 
    team/index
    index-team_guides
-   index-team_governance
    contribute/index
 
 Why have a Team Compass?
 ========================
 
-This repository helps the JupyterHub team and Binder team set a weekly
-course for project activity. Our overriding goal is continuous team and
-project improvement.
+This repository helps the JupyterHub team and Binder team align on our structure, policy, and goals.
+Our overriding goal is continuous team and project improvement.
 
 As projects and their growth evolve rapidly, the contents of this repo
 should aid us in setting project direction and adjusting the course as

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,6 @@
 myst_parser
 pandas
 pydata_sphinx_theme
-sphinx>=4
 sphinx-autobuild
 sphinx_copybutton
 sphinx_design
diff --git a/docs/talking.rst b/docs/talking.rst
@@ -1,8 +1,8 @@
 .. _talking:
 
-===============================================================
-Resources for giving presentations and talks about the Projects
-===============================================================
+==============================
+Giving presentations and talks
+==============================
 
 The JupyterHub and Binder projects are both community-driven. This means that we
 rely on members of the community for spreading the word about these projects as well

diff --git a/docs/team/binder-infrastructure.md b/docs/team/binder-infrastructure.md
@@ -0,0 +1,31 @@
+# `mybinder.org` infrastructure
+
+The `mybinder.org` service has some dedicated infrastructure that is unique to this service.
+We describe the major pieces below:
+
+## The `mybinder.org` domain
+
+The `mybinder.org` domain is owned by Chris Holdgraf ([@choldgraf](https://github.com/choldgraf)).
+The registrar for this domain is [BlueHost](https://bluehost.com).
+The email address with contact information for the domain is `[email protected]`.
+
+```{admonition} TODO
+In the future we wish to transfer ownership of this domain away from Chris's personal account.
+However, it is unclear what is the best way to do this right now, and so we are waiting for clarification from the Jupyter project at-large about how the project itself can own mybinder.org instead of Chris. We also plan to use a contact email for this domain that has fewer people on it than the entire team, but are using `[email protected]` as a stop-gap measure for now to increase our bus factor.
+```
+
+## DNS entries for `mybinder.org`
+
+The DNS for `mybinder.org` is handled by [CloudFlare](https://www.cloudflare.com/), by a central Jupyter account.
+
+(shared:gcp)=
+## Google Cloud Platform (GCP) Project
+
+The Binder Team uses a GCP project with id [`binderhub-288415`](https://console.cloud.google.com/home/dashboard?project=binderhub-288415) to host `gke.mybinder.org` and top level federation services at `mybinder.org`. The `binderhub-288415` GCP project resides in the GCP organization [`jupyter.org`](https://console.cloud.google.com/iam-admin/iam?organizationId=920697752286).
+
+The `binderhub-288415` GCP project is currently funded by a grant from Google, as represented as GCP credits. The credits belong to billing account belonging to the GCP organization `jupyter.org`, as can be seen [under its billing section](https://console.cloud.google.com/billing?organizationId=920697752286).
+
+## Other cloud deployments in the federation
+
+There are a number of other cloud deployments in the BinderHub federation, but these are not centrally managed by the Binder Team.
+Instead, they are managed by the individuals and organizations that represent each of the BinderHubs in the federation.
diff --git a/docs/team/index.rst b/docs/team/index.rst
@@ -1,20 +1,12 @@
 .. _jupyterhub-team:
 
-==============
-About our team
-==============
+========
+Our team
+========
 
 This page describes the official team members of the JupyterHub community.
 For information about what these teams mean and how you can join, see :doc:`structure`.
 
-For more information about the team, see the sections to the left:
-
-.. toctree::
-   :maxdepth: 2
-
-   structure
-   ../meetings/index
-
 Here is the current JupyterHub team (listed alphabetically, with affiliation, and main areas of contribution):
 
 **Min Ragan-Kelley** acts as the team lead for the JupyterHub organization.

diff --git a/docs/team/repository-code-standards.md b/docs/team/repository-code-standards.md
@@ -1,4 +1,4 @@
-# Repository Management and Code Standards
+# Repository management and code standards
 
 JupyterHub projects should take advantage of pre-commit and tools to help maintain consistent formatting within a repo to improve overall code quality, review efficiency, and readability of code.
 Sensible use of pre-commit to run formatting tools and code linters can add consistency and improve maintainability.

diff --git a/docs/team/shared-infrastructure.md b/docs/team/shared-infrastructure.md
@@ -45,31 +45,4 @@ It contains a variety of design assets from many projects, here's a preview belo
 
 ## `mybinder.org` infrastructure
 
-The `mybinder.org` service has a few pieces related to the domain that are described below:
-
-### Ownership of the `mybinder.org` domain
-
-The `mybinder.org` domain is owned by Chris Holdgraf ([@choldgraf](https://github.com/choldgraf)).
-The registrar for this domain is [BlueHost](https://bluehost.com).
-The email address with contact information for the domain is `[email protected]`.
-
-```{admonition} TODO
-In the future we wish to transfer ownership of this domain away from Chris's personal account.
-However, it is unclear what is the best way to do this right now, and so we are waiting for clarification from the Jupyter project at-large about how the project itself can own mybinder.org instead of Chris. We also plan to use a contact email for this domain that has fewer people on it than the entire team, but are using `[email protected]` as a stop-gap measure for now to increase our bus factor.
-```
-
-### DNS entries for `mybinder.org`
-
-The DNS for `mybinder.org` is handled by [CloudFlare](https://www.cloudflare.com/), by a central Jupyter account.
-
-(shared:gcp)=
-### Google Cloud Platform (GCP) Project
-
-The Binder Team uses a GCP project with id [`binderhub-288415`](https://console.cloud.google.com/home/dashboard?project=binderhub-288415) to host `gke.mybinder.org` and top level federation services at `mybinder.org`. The `binderhub-288415` GCP project resides in the GCP organization [`jupyter.org`](https://console.cloud.google.com/iam-admin/iam?organizationId=920697752286).
-
-The `binderhub-288415` GCP project is currently funded by a grant from Google, as represented as GCP credits. The credits belong to billing account belonging to the GCP organization `jupyter.org`, as can be seen [under its billing section](https://console.cloud.google.com/billing?organizationId=920697752286).
-
-### Other cloud deployments in the federation
-
-There are a number of other cloud deployments in the BinderHub federation, but these are not centrally managed by the Binder Team.
-Instead, they are managed by the individuals and organizations that represent each of the BinderHubs in the federation.
+See [](binder-infrastructure.md) for more details.