Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refactor docs/spec to use mdbook #1161

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Conversation

samlaf
Copy link
Contributor

@samlaf samlaf commented Jan 25, 2025

Closes EDGA-821
Still a wip so leaving as DRAFT, but curious for people's opinion here.

Using https://rust-lang.github.io/mdBook/index.html to publish the spec and further technical documentation in one place.
Mdbook has mathjax support, but they somehow don't support $...$ notation, so we have to replace all of them with \\( \\) (not sure whether this is mathjax-specific syntax or if latex supports this syntax as well). I changed all the $s in overview.md but haven't touched the other pages yet.

To view the book, need to

cargo install mdbook
# checkout this branch
cd docs/spec
mdbook serve --open

Looks like
image
for now but we'll prob want to reorganize the overview into a more book-like format.

Why are these changes needed?

Checks

  • I've made sure the tests are passing. Note that there might be a few flaky tests, in that case, please comment that they are not relevant.
  • I've checked the new test coverage and the coverage percentage didn't drop.
  • Testing Strategy
    • Unit tests
    • Integration tests
    • This PR is not tested :(

@samlaf samlaf marked this pull request as draft January 25, 2025 21:03
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.

1 participant