[DRAFT] Upgrade to JupyterBook

.readthedocs.yml

@@ -4,18 +4,17 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "3.12"
     nodejs: "16"
-
-sphinx:
-  configuration: conf.py
-  builder: dirhtml
+  commands:
+    - pip install -r requirements.txt
+    - cd scripts; python feature-table.py  # Generate the feature table in about/distributions/index.md
+    - cd scripts; python download-figures.py  # Download figures not in the GH repo
+    - jupyter-book build --builder dirhtml .
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r _build/dirhtml/* $READTHEDOCS_OUTPUT/html/
 
 # Explicitly opt out of trying to build additional formats such as PDF and ePub
-formats: []
-
-python:
-  install:
-    - requirements: requirements.txt
+formats: []

_config.yml

@@ -0,0 +1,113 @@
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# Users are expected to override these values in their own `_config.yml` file.
+# This is also the "master list" of all allowed keys and values.
+
+#######################################################################################
+# Book settings
+title                       : Hub Service Guide  # The title of the book. Will be placed in the left navbar.
+author                      : 2i2c  # The author of the book
+copyright                   : "2024"  # Copyright year to be placed in the footer
+version                     : "0.1"
+logo                        : ""  # A path to the book logo
+# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
+exclude_patterns            : [_build, Thumbs.db, .DS_Store, README.md, .github, .nox, CONTRIBUTING.md, "**.ipynb_checkpoints"]
+# Auto-exclude files not in the toc
+only_build_toc_files        : false
+
+#######################################################################################
+# Parse and render settings
+parse:
+  myst_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+    # - amsmath
+    - colon_fence
+    - deflist
+    - dollarmath
+    # - html_admonition
+    # - html_image
+    - linkify
+    # - replacements
+    # - smartquotes
+    - substitution
+    - tasklist
+  myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
+  myst_dmath_double_inline: true  # Allow display math ($$) within an inline context
+
+#######################################################################################
+# HTML-specific settings
+html:
+  favicon                   : "images/favicon.ico"  # A path to a favicon image
+  use_edit_page_button      : false  # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in
+  use_repository_button     : true  # Whether to add a link to your repository button
+  use_issues_button         : false  # Whether to add an "open an issue" button
+  use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
+  extra_footer              : ""  # Will be displayed underneath the footer.
+  google_analytics_id       : ""  # A GA id that can be used to track book views.
+  home_page_in_navbar       : false  # Whether to include your home page in the left Navigation Bar
+  baseurl                   : "https://docs.2i2c.org/"  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
+  analytics:
+
+  comments:
+    hypothesis              : false
+    utterances              : false
+  announcement              : "" # A banner announcement at the top of the site.
+
+#######################################################################################
+# LaTeX-specific settings
+latex:
+  latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
+  use_jupyterbook_latex     : true # use sphinx-jupyterbook-latex for pdf builds as default
+
+#######################################################################################
+# Launch button settings
+launch_buttons:
+  notebook_interface        : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url             : ""  # The URL of the BinderHub (e.g., https://mybinder.org)
+  jupyterhub_url            : ""  # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
+  thebe                     : false  # Add a thebe button to pages (requires the repository to run on Binder)
+  colab_url                 : "" # The URL of Google Colab (https://colab.research.google.com)
+
+repository:
+  url                       : https://github.com/2i2c-org/docs  # The URL to your book's repository
+  path_to_book              : ""  # A path to your book's folder, relative to the repository root.
+  branch                    : main  # Which branch of the repository should be used when creating links
+
+#######################################################################################
+# Advanced and power-user settings
+sphinx:
+  extra_extensions          :   # A list of extra extensions to load by Sphinx (added to those already used by JB).
+    - myst_nb
+    - sphinx_copybutton
+    - sphinx_design
+    - sphinx.ext.intersphinx
+    - sphinxext.rediraffe
+  local_extensions          :   # A list of local extensions to load by sphinx specified by "name: path" items
+  recursive_update          : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false)
+  config                    :   # key-value pairs to directly over-ride the Sphinx configuration
+    html_theme              : sphinx_2i2c_theme
+    intersphinx_mapping     :
+      tc:
+        - 'https://team-compass.2i2c.org'
+        - null
+      infra:
+        - 'https://infrastructure.2i2c.org'
+        - null
+      jb:
+        - 'https://jupyterbook.org/en/stable'
+        - null
+      z2jh:
+        - 'https://z2jh.jupyter.org/en/latest'
+        - null
+    intersphinx_disabled_reftypes : ["*"] # prevent local references from resolving to external docs
+    rediraffe_branch       : main
+    rediraffe_redirects    :
+      # Added around 2022-09
+      about/overview.md: about/service/index.md
+      about/pricing/index.md: about/service/options.md
+      # Added 2022-11-29
+      about/service/roles.md: about/service/shared-responsibility.md
+      about/service/team.md: about/service/shared-responsibility.md
+    linkcheck_ignore       :
+      - "https://openstoragenetwork.org*"  # It incorrectly fails with `Max retries exceeded with url`
+      - "https://docs.github.com*"  # Because docs.github.com returns 403 Forbidden errors
+    linkcheck_anchors      : false

_toc.yml

@@ -0,0 +1,20 @@
+root: index
+entries:
+- file: support
+- file: about/terminology
+  entries:
+  - file: about/distributions/index
+    entries:
+    - file: about/distributions/education
+    - file: about/distributions/research
+  - file: about/service/index
+    entries:
+    - file: about/service/comparison
+    - file: about/service/options
+    - file: about/service/service-objectives
+    - file: about/service/shared-responsibility
+- file: community/content
+  entries:
+  - file: community/events
+  - file: community/strategy
+- file: topic/cloud-costs

about/distributions/index.md

@@ -3,7 +3,7 @@
 2i2c builds and operates **distributions of JupyterHubs** that are tailored for particular use-cases.
 These services share many of the same infrastructure components, but have customizations and optimizations that are more domain- or community-specific.
 
-```{figure} https://drive.google.com/uc?export=download&id=1vL8ekAtUQ4TEik4-oWIn36VAOITdlmpR
+```{figure} ../../images/hub-overview.png
 :width: 80%
 
 A high-level technical overview of an Interactive Computing Service collaboratively run by 2i2c and a community of practice. Each hub is a JupyterHub Distribution with a collection of community-led open source projects that are customized for a particular use-case.
@@ -69,7 +69,7 @@ Your 2i2c JupyterHub has an environment that has been created for your particula
 
 All of the configuration and deployment scripts for the 2i2c JupyterHub can be found at [the `infrastructure/` repository](https://github.com/2i2c-org/infrastructure). This repository contains both the deployment code as well as documentation that explains how it works. It should be treated as "for advanced users only", and is provided for transparency and as a guide for the community to follow if they wish to manage their own infrastructure similar to 2i2c JupyterHub.
 
-To learn about how the `infrastructure/` repository works, we recommend checking out the [`infrastructure` documentation](infra:index).
+To learn about how the `infrastructure/` repository works, we recommend checking out the {doc}`Infrastructure documentation <infra:index>`.
 
 See the next sections for more information about each hub distribution.
 
@@ -86,7 +86,7 @@ As members of the JupyterHub team, we are constantly looking for ways to improve
 2i2c will not collect user data for any purpose beyond what is required in order to run a JupyterHub.
 Depending on the choices of your community the hub might contain identifiable information (e.g., e-mail addresses used as usernames for authentication), but this will remain within your hub's configuration and is not shared publicly.
 
-Our {role}`Site Reliability Engineer`s will have access to all of the information that is inside a hub (which it requires in order to debug problems and and assist with upgrades), however we will not retain any of this data or move it *outside* of the hub, and will not retain it once the hub is shut down (except in order to transfer data to you at your request).
+Our {ref}`Site Reliability Engineer<role:site-reliability-engineer>`s will have access to all of the information that is inside a hub (which it requires in order to debug problems and and assist with upgrades), however we will not retain any of this data or move it *outside* of the hub, and will not retain it once the hub is shut down (except in order to transfer data to you at your request).
 
 ## Monitored for abuse and unexpected costs