Skip to content

Conversation

@jfdm
Copy link
Collaborator

@jfdm jfdm commented Nov 21, 2025

Traditionally, Sphinx required authors to use reST and provided basic markdown support. Now, myST is a variant of markdown that incorporates many reST features but in a markdown many are familiar with.

This PR does the following:

  1. Introduce myST as a dependency, enabling authors to use myST for input;
  2. Change the style to sphinx-book-theme a more featured html style that enables more featured documentation to be written.
    Including, light/dark modes.
  3. Pull in bibtex tooling and 'copy button' for code.
  4. Provide instructions for managing python projects using the uv tool.

Description

Self-check

  • This is my first time contributing, I've carefully read CONTRIBUTING.md
    and I've updated CONTRIBUTORS.md with my name.
  • If this is a fix, user-facing change, a compiler change, or a new paper
    implementation, I have updated CHANGELOG_NEXT.md

Traditionally, Sphinx required authors to use reST and provided basic
markdown support. Now, myST is a variant of markdown that incorporates
many reST features but in a markdown many are familiar with.

This PR does the following:

1. Introduce myST as a dependency, enabling authors to use myST for
input;
2. Change the style to `sphinx-book-theme` a more featured html style
that enables more featured documentation to be written.
   Including, light/dark modes.
3. Pull in bibtex tooling and 'copy button' for code.
4. Provide instructions for managing python projects using the `uv` tool.
@jfdm
Copy link
Collaborator Author

jfdm commented Nov 21, 2025

I will update the changelog later.

@gallais
Copy link
Member

gallais commented Nov 21, 2025

Do you know if there's anywhere we can see the rendered result?

Files like uv.lock seem autogenerated (unless you're the SHA master who can see
through them like through matrix code :D); should we document how/when to
regenerate them or are we not expecting them to change?

@jfdm
Copy link
Collaborator Author

jfdm commented Nov 21, 2025

Do you know if there's anywhere we can see the rendered result?

urgh, I thought there would be something from my github. Alas no.

So I have dumped something temporary here

Files like uv.lock seem autogenerated (unless you're the SHA master who can see
through them like through matrix code :D); should we document how/when to
regenerate them or are we not expecting them to change?

We can add a note. For uv, the lock file is generated automatically when uv is invoked.

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.

2 participants