Merge pull request #587 from choldgraf/binder-resources

Reorganize documentation to be more modular and cleanly grouped

docs/conf.py

@@ -1,109 +1,34 @@
 #!/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",
+    "sphinxext.rediraffe",
+    "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
-
-
-def setup(app):
-    app.add_css_file("custom.css")
+project = "Team Compass"
+copyright = "2022, JupyterHub Team and Binder Team"
+author = "JupyterHub Team and Binder Team"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- 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 +37,45 @@ 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)
+
+# -- Options for the rediraffe extension -------------------------------------
+# ref: https://github.com/wpilibsuite/sphinxext-rediraffe#readme
+#
+# This extensions help us relocated content without breaking links. If a
+# document is moved internally, a redirect like should be configured below to
+# help us not break links.
+#
+rediraffe_branch = "main"
+rediraffe_redirects = {
+    # Redirects added 2022-11-25 for PR 587
+    "building-blocks/index": "index-team_policies",
+    "building-blocks/readme-badges": "practices/readme-badges",
+    "contribute/index": "index-team_guides",
+    "index-team_governance": "index-team_policies",
+    "milestones": "resources/milestones",
+    "talking": "practices/talking",
+    "team/adding-members": "practices/adding-members",
+    "team/community-strategy": "resources/community-strategy",
+    "team/member-guide": "index-team_policies",
+    "team/repository-code-standards": "practices/repository-code-standards",
+    "team/shared-infrastructure": "resources/shared-infrastructure",
+
+    # Add additional redirects below if you relocate documents
+    # "old/folder/old-file": "new-folder/new-file",
+}

docs/contribute/skills.md

@@ -1,4 +1,4 @@
-# Skills and ways to contribute
+# Useful skills and ways to contribute
 
 There are many ways that you can contribute to the JupyterHub / Binder projects.
 This page suggests some pathways for community members to learn new skills and
@@ -112,13 +112,12 @@ all obvious. If you'd like to make a contribution and you're not sure where to s
 a good rule of thumb is to open an issue or reach out to another team member to help
 you scope the work you'd like to do, and to set expectations.
 
-## Links
-
-* The [UC Berkeley JupyterHubs documentation](https://docs.datahub.berkeley.edu/en/latest/pre-reqs.html)
-  has a similar scope and set of information.
-
-## Resources for Learning
+## Resources for learning
 
 In this section, we gather some introductory materials for learning the aforementioned tools.
 
-- **[Learning-k8s](https://github.com/knrt10/kubernetes-basicLearning)**: A step-by-step guide to learning the basics of Kubernetes
+* The [UC Berkeley JupyterHubs documentation](https://docs.datahub.berkeley.edu/en/latest/pre-reqs.html)
+  has a similar scope and set of information.
+* **[Learning-k8s](https://github.com/knrt10/kubernetes-basicLearning)**: A step-by-step guide to learning the basics of Kubernetes
+* [**The mybinder SRE guide**](https://mybinder-sre.readthedocs.io/en/latest/) is a set of resources for running mybinder.org.
+  It contains tips, snippets, lessons-learned etc for running a large, public kubernetes cluster.

docs/index-team_guides.rst

@@ -1,17 +1,32 @@
 .. _guides_index:
 
-==============
-Team Resources
-==============
+=====================
+Contributor resources
+=====================
 
 Resources and guides for team members to help us coordinate and work together more effectively.
 
-.. toctree::
+**Contributor guide** is a resource for those interested in learning more about JupyterHub and how they can contribute to this project.
 
-   team/member-guide
-   team/repository-code-standards
-   team/adding-members
-   team/shared-infrastructure
-   talking
-   building-blocks/index
-   team/community-strategy
+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:: 
+   :caption: Contributor guide
+   :maxdepth: 2
+
+   contribute/guide
+   contribute/skills
+
+**Team information** is meant to share information and context across team members, and align us on a plan of action.
+
+.. toctree:: 
+   :caption: Team information
+   :maxdepth: 2
+
+   meetings/index
+   resources/shared-infrastructure
+   resources/binder-infrastructure
+   resources/milestones
+   contribute/repository-info
+   resources/community-strategy

docs/index-team_policies.rst

@@ -0,0 +1,33 @@
+Team policies and standards 
+===========================
+
+**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 practices** describe our operational policies and practices.
+
+.. toctree::
+   :caption: Team practices
+   :maxdepth: 2
+
+   practices/communication
+   practices/adding-members 
+   practices/talking
+   practices/check-ins
+
+**Technical practices** describe our standards and processes around technical infrastructure.
+
+.. toctree::
+   :caption: Technical practices
+
+   practices/merging
+   practices/repository-code-standards
+   practices/readme-badges

docs/index.rst

@@ -10,13 +10,11 @@ Team Compass for JupyterHub and Binder
    :target: https://hackmd.io/u2ghJJUCRWK-zRidCFid_Q?view
    :alt: monthly agenda
 
-This page contains links to the notes from team meetings
-with the JupyterHub community. For more some more technical information
-and links to various JupyterHub repositories, see the
-`Team Compass README <https://github.com/jupyterhub/team-compass>`_.
+Our Team Compass contains team practices, policies, and resources to help one another align and contribute.
+It also has helpful information for team members, like shared infrastructure and accounts, resources to learn how to contribute, etc.
 
-Team Compass Resources
-======================
+We use [**Team Compass issues**](https://github.com/jupyterhub/team-compass/issues)
+to discuss specific, actionable things related to the *team* (e.g., discussing whether to change something in the team-compass repo).
 
 The following pages contain information about the JupyterHub/Binder
 teams, resources for community members, and team practices for
@@ -26,16 +24,14 @@ governance and planning.
    :maxdepth: 2
 
    team/index
+   index-team_policies
    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 primary 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