Skip to content

Conversation

@choldgraf
Copy link
Contributor

@choldgraf choldgraf commented Nov 7, 2025

This updates our governance documentation to use Jupyter Book 2, which was released this week! Here are major updates:

  • It moves all of our governance docs to a docs/ folder, so we don't confuse repository items (like .github) with the actual governance docs.
  • It adds a noxfile to make the governance docs build easier locally (nox -s docs-live)
  • It updates our configuration to use Jupyter Book 2
  • It fixes a bunch of broken references we had in there
  • It adds a redirect script that was inspired by @pancakereport in data-8/textbook@49934cf so that old-style URLs redirect to the new URLs.
  • It does not change any content.

Issues

To preview this:

Use the GH CLI and nox. NodeJS is required.

gh pr checkout https://github.com/jupyter/governance/pull/299
pip install nox
nox -s docs-live

Suggested review

This touches a bunch of files and configuration, but also doesn't change any content. I suggest that somebody gives the preview site a look and notes anything that seems obviously wrong. If not, then I think we should just merge this and iteratively fix things from there. It's also going to be hard to know if the HTML redirects really work until it's merged, so I'm happy to iterate on that if they don't.

@jasongrout
Copy link
Member

Thanks! I rendered it and things look great. I also glanced through the diff and nothing problematic stuck out.

Copy link
Member

@jasongrout jasongrout left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I rendered it and things look great. I also glanced through the diff and nothing problematic stuck out.

@jasongrout jasongrout merged commit 5c4a238 into main Nov 7, 2025
1 check passed
@jasongrout
Copy link
Member

Unfortunately, I'm finding these changes broke a lot of links in various docs. For example https://github.com/jupyterhub/jupyterhub/actions/runs/19182079655/job/54840999714?pr=5199 shows:

contributing/index.md:9 https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md
    404 Client Error: Not Found for url: https://github.com/jupyter/governance/blob/HEAD/conduct/reporting_online.md
contributing/index.md:9 https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md
    404 Client Error: Not Found for url: https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md

@jasongrout
Copy link
Member

But that's what you get for deep-linking into a file in a repo using the HEAD. I think the right thing is to change the jupyterhub docs, but just fyi that there are things that are breaking from this refactor.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants