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

Add MyST (Markdown) examples to "cross referencing with Sphinx" guide #8437

Merged
merged 4 commits into from
Aug 24, 2021

Conversation

astrojuanlu
Copy link
Contributor

This adds MyST (Markdown) examples to "cross-referencing with Sphinx" guide by using https://pypi.org/project/sphinx-tabs/, similarly to how we did in #8283. Basically all our reST samples are in our Sphinx guides - I started with one of them in this pull request to make reviews easier, but I can add a couple more guides.

While I was at it, I also reworded some parts to use second person and to clarify the role of reStructuredText vs Sphinx and put it on the same ground as MyST.

Got into a couple of rabbit holes while doing it, for example executablebooks/mdit-py-plugins#28. Also, "in-line" references are not supported at the moment, we didn't open an issue for it.

@astrojuanlu astrojuanlu requested a review from a team August 23, 2021 18:36
Copy link
Member

@ericholscher ericholscher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simple enough. Definitely a good example of the struggle of the markdown support, since rST stuff is also in the copy in various places.

@@ -263,7 +360,7 @@ That will be rendered as:
Invalid targets
---------------

If we reference an invalid or undefined target Sphinx will warn us.
If you reference an invalid or undefined target Sphinx will warn us.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guessing we'll do a simple style guide here soon :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Getting closer :)

@astrojuanlu astrojuanlu merged commit a2cff49 into master Aug 24, 2021
@astrojuanlu astrojuanlu deleted the markdown-examples-xref-sphinx branch August 24, 2021 06:10
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.

None yet

2 participants