docs: fail on build warnings, fix warnings, refresh conf.py

.github/workflows/test-docs.yaml

@@ -0,0 +1,30 @@
+# This is a GitHub workflow defining a set of jobs with a set of steps.
+# ref: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+#
+name: Test docs
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - "dependabot/**"
+      - "pre-commit-ci-update-config"
+  workflow_dispatch:
+
+jobs:
+  test-docs:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install deps
+        run: pip install -r requirements.txt
+
+      # linkcheck is done separately from this in doc-links.yml, scheduled to
+      # run every day and open/update an issue
+      - name: make dirhtml
+        run: |
+          make dirhtml SPHINXOPTS='--color -W --keep-going'

administration/authentication.md

@@ -6,7 +6,7 @@ This page describes the accounts that we use for authentication in our JupyterHu
 
 We have an annual [**Essential Service** membership with CILogon](https://www.cilogon.org/subscribe).
 This allows us to use the CILogon service for authenticating users on our hubs.
-See [the `infrastructure/` docs](infra:hub-deployment-guide/configure-auth/cilogon) for more information.
+See {external+infra:doc}`the infrastructure docs <hub-deployment-guide/configure-auth/cilogon>` for more information.
 
 ## Auth0
 

conf.py

@@ -1,19 +1,17 @@
-import os
 from pathlib import Path
 from subprocess import run
 
 # -- Project information -----------------------------------------------------
-
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+#
 project = "Team Compass"
 copyright = "2023, 2i2c"
 author = "2i2c"
 
 
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# -- General Sphinx configuration ---------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+#
 extensions = [
     "myst_nb",
     "sphinx_design",
@@ -22,45 +20,75 @@
     "sphinx_togglebutton",
     "sphinxext.rediraffe",
 ]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".github", ".nox", "README.md"]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".github", ".nox", "README.md"]
+
+# -- General MyST configuration -----------------------------------------------------
+# ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
+#
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "linkify",
+    "tasklist",
+]
 
 
-# -- Options for HTML output---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# -- Options for HTML output -------------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 #
-html_theme = "sphinx_2i2c_theme"
 html_static_path = ["_static"]
-html_title = "Team Compass"
+html_css_files = ["custom.css"]
 
-show_navbar_depth = 3
+# sphinx-2i2c-theme inherits from sphinx-book-theme, that in turn inherits from
+# pydata-sphinx-theme. Due to this, all their configuration can be relevant.
+#
+# sphinx-2i2c-theme ref:   https://github.com/2i2c-org/sphinx-2i2c-theme
+# sphinx-book-theme ref:   https://sphinx-book-theme.readthedocs.io/en/stable/reference.html
+# pydata-sphinx-theme ref: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html
+#
+html_theme = "sphinx_2i2c_theme"
 html_theme_options = {
     "repository_url": "https://github.com/2i2c-org/team-compass",
     "repository_branch": "main",
     "use_repository_button": True,
     "use_edit_page_button": True,
 }
-myst_enable_extensions = [
-    "colon_fence",
-    "deflist",
-    "dollarmath",
-    "linkify",
-    "tasklist",
-]
 
+
+
+# -- Options for intersphinx extension ---------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+#
+# The extension makes us able to link like to other projects like below.
+#
+#     {external+infra:doc}`folder/subfolder/file`
+#     {external+infra:ref}`reference-label-name-here`
+#     {external+infra:ref}`explicit link title <reference-label-name-here>`
+#
+# To see what we can link to, do the following where "objects.inv" is appended
+# to the sphinx based website:
+#
+#     python -m sphinx.ext.intersphinx https://docs.2i2c.org/objects.inv
+#     python -m sphinx.ext.intersphinx https://infrastructure.2i2c.org/objects.inv
+#
 intersphinx_mapping = {
     "docs": ("https://docs.2i2c.org/", None),
     "infra": ("https://infrastructure.2i2c.org/", None),
 }
 
+# intersphinx_disabled_reftypes set based on recommendation in
+# https://docs.readthedocs.io/en/stable/guides/intersphinx.html#using-intersphinx
+intersphinx_disabled_reftypes = ["*"]
+
+
+
+# -- Options for linkcheck builder -------------------------------------------
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+#
 # Disable linkcheck for anchors because it throws false errors for any JS anchors
 linkcheck_anchors = False
 linkcheck_ignore = [
@@ -75,11 +103,24 @@
     "https://app.asana.com*",  # Because it has some kind of security that returns a 403
 ]
 
-# -- Sphinx setup script ---------------------------------------------------
 
+
+# -- 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, put its path as a dictionary key in the
+# redirects dictionary below and its new location in the value.
+#
+rediraffe_branch = "main"
+rediraffe_redirects = {
+    "get-started": "operations/index",
+}
+
+
+
+# -- Sphinx setup script ---------------------------------------------------
 def setup(app):
-    app.add_css_file("custom.css")
-
     # Add a `role` domain that we can reference in our text.
     # To add a new role, use the `role` directive just above the section where you describe it.
     #
@@ -96,15 +137,3 @@ def setup(app):
 # The token exists in our RTD environmet so it should work there.
 path_script = Path(__file__).parent / "_data/support_stewards/gen_support_stewards.py"
 run(f"python {path_script}", shell=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, put its path as a dictionary key in the
-# redirects dictionary below and its new location in the value.
-#
-rediraffe_branch = "main"
-rediraffe_redirects = {
-    "get-started": "operations/index",
-}

engineering/reviewing.md

@@ -36,4 +36,4 @@ Not all of them are followed strictly, though some are more important than other
 
 Changing active infrastructure is a bit different from developing technology that is not immediately in production.
 As such, we follow some more specific guidelines for these kinds of changes.
-See {ref}`infra:infrastructure:review`.
+See {external+infra:ref}`infrastructure:review`.

engineering/strategy.md

@@ -17,7 +17,7 @@ We'll focus on the following cloud providers:
 
 In the short term, we favor deploying hubs on Google Cloud Platform.
 This is because GCP has the most stable Kubernetes offering of all of the cloud providers.
-We follow [team guidelines for when to deploy new Kubernetes clusters](infra:cluster:when-to-deploy).
+We follow {external+infra:ref}`team guidelines for when to deploy new Kubernetes clusters <cluster:when-to-deploy>`.
 For new hubs that don't require their own Kubernetes cluster, we plan to run them on Google Cloud until our team has capacity to run more infrastructure across Azure and AWS.
 
 ## Why Jupyter and JupyterHub?

finance/accounting.md

@@ -70,7 +70,7 @@ To find this number, follow these steps:
 CS&S prepares our monthly reports using last-month's data.
 This means that the definition of `Net Income` is true as of the end of the window used in that report.
 This is usually about a month in the past.
-See [](accounting:remaining-in-contracts) for how to correct for this gap.
+See [](contracts:amount-remaining) for how to correct for this gap.
 ```
 
 ### Detailed monthly reports description

operations/strategy.md

@@ -1,8 +1,8 @@
 # Coordination strategy and goals
 
 2i2c is a distributed organization, and believes strongly in following practices that are inclusive, participatory, and collaborative.
-It has team members spread out over many time zones working on a variety of projects. 
-There are many guides and tips for distributed working[^distributed-work1], and we've tried to distill a few key components for our workflows:
+It has team members spread out over many time zones working on a variety of projects.
+There are many guides and tips for distributed working[^distributed-work1], and we've tried to distill a few key components for our workflows.
 
 ## Our goals
 
@@ -31,6 +31,13 @@ Different people have different preferred methods of engagement and communicatio
 
 Err on the side of updating the team more often than not.  Nobody should be surprised when something gets done - especially nothing major. Your work should be as transparent to others as possible!
 
+rems
+
 ## Distributed-first operations
 
-[^distributed-work1]: **References for Distributed Work**: [The GitLab remote work guide](https://about.gitlab.com/company/culture/all-remote/guide/), [the future of work is written](https://increment.com/remote/future-of-work-is-written/), [RFCs as a management tool](https://buriti.ca/6-lessons-i-learned-while-implementing-technical-rfcs-as-a-management-tool-34687dbf46cb)
+<!--
+    This comment is a workaround to the sphinx build error:
+
+    operations/strategy.md:0: ERROR: Document or section may not begin with a transition.
+-->
+[^distributed-work1]: **References for Distributed Work**: [The GitLab remote work guide](https://about.gitlab.com/company/culture/all-remote/guide/), [the future of work is written](https://increment.com/remote/future-of-work-is-written/), [RFCs as a management tool](https://buriti.ca/6-lessons-i-learned-while-implementing-technical-rfcs-as-a-management-tool-34687dbf46cb)

operations/team-practices/feedback.md

@@ -95,7 +95,7 @@ However, when the intent or the act of giving feedback deviates from this, it is
   - It’s being done publicly
   - It’s not being done to help them grow
 
-#### Deferring feedback with “Not now” 
+### Deferring feedback with “Not now”
 
 “Not now” isn’t a no, and it’s also a reasonable thing to say - if you know you’ll have a hard time receiving feedback right now, suggest another, better time. 
 
@@ -141,7 +141,7 @@ The best time to give or ask for feedback is around activities. Here are some ex
 
 ## Examples of “Good” vs “Bad” feedback
 
-#### Example 1
+### Example 1
 **Bad Feedback**
 > You’re difficult to work with
 
@@ -157,19 +157,19 @@ In 1A, the feedback is better as it provides more concise information an leads t
 1b is even better because it is more timely. Additionally, it captures the _situation, behavior and the impact_.
 
 
-#### Example 2
+### Example 2
 **Bad Feedback**
 >Let me share some feedback with you… you really should do... because from my personal experience…
 
 The feedback isn’t about you and it should not include your advice or personal experiences
 
-#### Example 3
+### Example 3
 **Bad Feedback**
 >If you aren’t willing to do… then I’m going to have to let you go
 
 This isn’t considered feedback. It’s simply a veiled threat.
 
-#### Example 4
+### Example 4
 **Bad Feedback**
 >Here’s some good news…
 >But the bad news is…

product/pricing/strategy.md

@@ -42,7 +42,7 @@ In the future we may try to perform a more nuanced mapping of costs onto effort
 
 ### Pass-through cloud costs
 
-In addition to our monthly hub fees, we pass {external:docs:ref}`cloud infrastructure costs <costs:cloud>` directly to the communities we serve, without taking any percentage markup.
+In addition to our monthly hub fees, we pass {external+docs:ref}`cloud infrastructure costs <costs:cloud>` directly to the communities we serve, without taking any percentage markup.
 We do this for two reasons:
 
 1. In our eyes, we are running infrastructure _on behalf of each community_, and wish to act as if a member of that community were running the infrastructure themselves. We are simply being compensated for our time and expertise.

projects/managed-hubs/support.md

@@ -92,7 +92,7 @@ Support Triagers
 
   The primary responsibilities of the Support Triagers are:
 
-  - Ensure that we meet {ref}`our Support Service Level Objectives <docs:objectives:support>`.
+  - Ensure that we meet {external+docs:ref}`our Support Service Level Objectives <objectives:support>`.
   - Carry out [our support process](support:process).
   - Act as primary points of contact with {term}`Community Representative`s.
   - Trigger an [Incident Response](support:incident-response) if need be.