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

Change default Sphinx docs from reStructuredText to Markdown #3

Closed
4 tasks done
Spacecow99 opened this issue Jan 12, 2022 · 2 comments
Closed
4 tasks done

Change default Sphinx docs from reStructuredText to Markdown #3

Spacecow99 opened this issue Jan 12, 2022 · 2 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@Spacecow99
Copy link
Owner

Spacecow99 commented Jan 12, 2022

Considering our primary document hosting sources (Github, Github Pages and ReadTheDocs) all support Markdown in some shape or form, it is worth migrating our default sphinx documents over to Markdown by default and using the MyST package.

  • Rename files from *.rst to *.md
  • Reformat index.rst in to markdown
  • Add myst-parser as a docs dependency in pyproject.toml
  • Configure myst-parser and exclude .venv in conf.py
@Spacecow99 Spacecow99 self-assigned this Jan 12, 2022
@Spacecow99 Spacecow99 added this to To do in pyproject-package via automation Jan 12, 2022
@Spacecow99 Spacecow99 added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 12, 2022
@Spacecow99
Copy link
Owner Author

Beta version using myst-parser in branch feature/myst-markdown-conversion. Will merge when testing complete.

No need to exclude venv patterns in conf.py, was just an error on my part during initial experimentation.

@Spacecow99 Spacecow99 moved this from To do to In progress in pyproject-package Mar 4, 2022
@Spacecow99
Copy link
Owner Author

One thing that should be noted with this is that myst-parser still expects docstrings to be written in reStructuredText when using sphinx.ext.autodoc as detailed here. This is a myst-parser limitation outlined in Github issue #228.

pyproject-package automation moved this from In progress to Done Apr 16, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
Development

No branches or pull requests

1 participant