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

Guide: Cross-referencing with Sphinx #7326

Merged
merged 7 commits into from Aug 25, 2020
Merged

Guide: Cross-referencing with Sphinx #7326

merged 7 commits into from Aug 25, 2020

Conversation

stsewd
Copy link
Member

@stsewd stsewd commented Jul 27, 2020

A little longer than I expected, but not sure if we can remove content

Preview at https://docs--7326.org.readthedocs.build/en/7326/guides/cross-referencing-with-sphinx.html

Finding the reference name
--------------------------
Copy link
Member Author

@stsewd stsewd Jul 27, 2020

Choose a reason for hiding this comment

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

I'm tempted to recommend my plugin for neovim users 👀

@stsewd
Copy link
Member Author

stsewd commented Jul 27, 2020

/cc @choldgraf because of #7248 (comment) 😃

@stsewd stsewd requested a review from a team Jul 28, 2020
@choldgraf
Copy link
Contributor

choldgraf commented Jul 28, 2020

thanks for the ping - anything in particular that you'd like feedback on?

btw - any reason that these updates aren't being made to the Sphinx documentation as opposed to a separate RTD repo?

@stsewd
Copy link
Member Author

stsewd commented Jul 29, 2020

btw - any reason that these updates aren't being made to the Sphinx documentation as opposed to a separate RTD repo?

Most of the content is already in sphinx, but spread across multiple sections, I'll see if I can port some sections there.

thanks for the ping - anything in particular that you'd like feedback on?

I guess if examples are clear enough and if there is anything else missing that is worth including.

Copy link
Contributor

@choldgraf choldgraf left a comment

Sorry for the slowness! In general this looks really nice!

I had a few suggestions and thought it'd be easier to give them in a PR which I opened here: #7388 let me know if that looks OK!

I also made a couple of comments.

FYI I might be slow in responding as I am expecting a baby any time soon, just FYI!

- Not easy way to link to specific sections like paragraphs, figures, or code blocks.
- It only works for the html version of your documentation.

ReStructuredText has a built-in way to linking to elements,
Copy link
Contributor

@choldgraf choldgraf Aug 17, 2020

Choose a reason for hiding this comment

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

Shouldn't this be docutils as opposed to reStructuredText? I may be sensitive to this because MyST markdown also uses the same docutils cross-referencing :-)

I think it's fair to focus on reStructuredText given how common it is in the ecosystem, but just wanted to get in this note that there are other ways to write Sphinx documentation!

Copy link
Member Author

@stsewd stsewd Aug 17, 2020

Choose a reason for hiding this comment

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

I see rst as a markup language and MyST as another markup language (based on rst), and docutils is an implementation of the rst specification.

docs/guides/cross-referencing-with-sphinx.rst Show resolved Hide resolved
@stsewd
Copy link
Member Author

stsewd commented Aug 17, 2020

Thanks for the suggestions!

FYI I might be slow in responding as I am expecting a baby any time soon, just FYI!

Congrats! 👶

Copy link
Member

@humitos humitos left a comment

This guide is super useful. We should merge it soon! I left some improvements.

docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
docs/guides/cross-referencing-with-sphinx.rst Outdated Show resolved Hide resolved
@stsewd stsewd merged commit 1a5505f into master Aug 25, 2020
2 checks passed
@stsewd stsewd deleted the cross-reference-guide branch Aug 25, 2020
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

3 participants