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

Use MyST as the markup format #211

Open
3 of 4 tasks
bryanwweber opened this issue Jun 14, 2022 · 0 comments · May be fixed by #263
Open
3 of 4 tasks

Use MyST as the markup format #211

bryanwweber opened this issue Jun 14, 2022 · 0 comments · May be fixed by #263
Assignees
Labels
enhancement New feature or request work-in-progress

Comments

@bryanwweber
Copy link
Member

bryanwweber commented Jun 14, 2022

The MyST markup format is a combination of the best parts of Markdown and RestructuredText. It can be installed as a Sphinx extension, so upon completion of #209 we shouldn't have much trouble to add this as a dependency. I think tackling this issue is best done after completing #210, to avoid conflicts with any content changes needed for that issue.

We should consider using MyST-NB so that the documentation pages (especially the tutorials) can be executed at build time. Content can still be written as Markdown files, but code markup sections become executable, which would be useful to smoke out errors in content due to API changes, etc.

Action Items

  • Add dependency on the MyST parser extension
  • Update Sphinx configuration to use this extension
  • Use sphinx-design for native Bootstrap theme support (ADDED 18-JUN-2022, please pull the updated branch 😄)
  • Convert all prose content (tutorials, science, etc.) to use MyST markup

Non-Goals

  • Significant modifications or restructuring of content. This issue should focus on converting existing content to MyST format, not on adding, extending, modifying, or restructuring content.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request work-in-progress
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants