Skip to content

Upgrade our service documentation to the MyST engine - #311

Merged
agoose77 merged 28 commits into
mainfrom
maint/mystmd
Aug 4, 2026
Merged

Upgrade our service documentation to the MyST engine#311
agoose77 merged 28 commits into
mainfrom
maint/mystmd

Conversation

@choldgraf

@choldgraf choldgraf commented Aug 3, 2026

Copy link
Copy Markdown
Member

This PR upgrades our /docs site to use the new MyST engine! I believe that this should "just work" - let's see how the PR preview does.

🖼️ Here's the ReadTheDocs preview (for some reason it's not being auto-added to this PR? Maybe because of that action we have that calls it? EDIT: Fixed it by re-connecting the github app)

Plan for this PR

  • If somebody wants to review it, that'd be nice but not necessary. I've added @agoose77 but Angus if you're busy please don't feel obligated!
  • Unless there are objections I'll merge this on Wednesday.

What I did

Here are a few things that I did:

  • Added all the config etc for MyST
  • Updated a bunch of sphinx-specific roles (e.g. :ref:) to use MyST link syntax instead
  • Removed some custom roles we'd created (e.g. {role}) and just used myst labels for those
  • Updated the javascript for our support widget to instead use a myst anywidget - it has a transform that adds the button to every page by a little invisible node it puts at teh end of the page - this is a bit hacky but I couldn't figure out another way to embed JS on each page otherwise.
  • Added some footer / navbar / etc.
  • Created a new little MyST plugin here: https://github.com/myst-contrib/myst-gui-text and am using that for all our {guilabel} uses.
  • Fixed some broken links, moved files, etc.

There were some other cleanups here and there but that's the main stuff I can remember. This is another PR that touches a bunch of files, so maybe Angus could take a quick look and push whatever he changes he likes, and then merge when he thinks it's OK?


@choldgraf
choldgraf requested a review from agoose77 August 3, 2026 18:58
@choldgraf choldgraf changed the title Add initial myst config Upgrade our service documentation to the MyST engine Aug 3, 2026
@github-project-automation github-project-automation Bot moved this to To Be Refined in Product and Services Aug 3, 2026
@choldgraf choldgraf moved this from To Be Refined to In Review/Blocked in Product and Services Aug 3, 2026
@choldgraf choldgraf closed this Aug 4, 2026
@github-project-automation github-project-automation Bot moved this from In Review/Blocked to Done in Product and Services Aug 4, 2026
@choldgraf choldgraf reopened this Aug 4, 2026
@github-project-automation github-project-automation Bot moved this from Done to Up Next in Product and Services Aug 4, 2026
@agoose77
agoose77 merged commit fb16a41 into main Aug 4, 2026
1 check passed
@github-project-automation github-project-automation Bot moved this from Up Next to Done in Product and Services Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants