Migrate from nbsphinx to myst, myst-nb
Open
Nobody has claimed this yet.
contrib-help-wanted
enhancement
topic-documentation
- Dominant language
- Python
- Stars
- 4.2k
- Forks
- 1.4k
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 14
Description
Is your feature request related to a problem?
I think we should switch to MyST markdown for our docs. I've been using MyST markdown and MyST-NB in docs in other projects and it works quite well.
Advantages:
- We get HTML reprs in the docs (example) which is a big improvement. (#6620)
- I think many find markdown a lot easier to write than RST
There's a tool to migrate RST to MyST (RTD's migration guide).
Describe the solution you'd like
No response
Describe alternatives you've considered
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the MyST markdown documentation, MyST-NB documentation, and Read the Docs' RST-to-MyST migration guide. Compare the current nbsphinx-based documentation setup with the proposed migration, and define completion as the docs building with MyST and MyST-NB while retaining existing content and enabling the cited HTML representations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, markdown, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100