Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
Beginning of new Sphinx tutorial #9276
Beginning of new Sphinx tutorial #9276
Changes from 4 commits
70ee9bc
39b5564
337ee6a
ffa8e11
1631291
bfd3b51
d6cb2d0
5b3e5d8
bfca913
1da5ab5
95519b3
c8a3a25
2b0131d
ce727e3
565713d
1ffbfa7
a2a8a07
aee105c
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Answer each question as follows.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I observed that you tend to remove colons at the end of sentences that end in "as follows", whereas you are okay with some other sentences that precede enumerations or instructions. I'd be keen to learn more, would you please share some explanations about it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
English.SE seems to disagree https://english.stackexchange.com/a/394875/20057
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First I should preface that the dominant practice should be continued, but I don't know what that is for Sphinx. A style guide should be adopted. @tk0miya is there an established preferred style in Sphinx for how to end a sentence when followed by a list or code block?
There are varying opinions about ending a sentence with a colon or a period when followed by a list, but not many about following it with code. The context and audience need to be considered. For example, technical documentation versus a narrative tutorial. Even American and English English don't agree. No one way is correct, as they are all opinions. I may have been inconsistent when spotting these instances and reviewing them. Apologies for that.
Some guides prefer to end all sentences with a period and never a colon. I prefer this style because it prevents the confusion of what punctuation to use when ending a sentence, as they always end with a period without exception. It avoids sentence fragments, such as "For example:" and encourages the writer to form complete sentences. This is especially helpful for visually impaired readers and screen readers. It prevents the confusion of whether to use
:
or::
when a code block follows to get syntax highlighting."As follows", "following", and similar phrases are hints to readers—especially visually impaired or people with reading comprehension impairments—that something is coming up related to this sentence, so I almost always include them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
AFAIK, there are no policies and rules for them.
IMO, reST provides
::
syntax to notate a code-block after a paragraphThis is rendered as following.
So I think the sentences that end with a colon just before code-block are commonly used in reST documents. I've usually written them also. To imitate the colon at the tail of the sentence, I've usually use a single colon and
code-block
directive as followsOn the other hand, I don't see the sentences that end with a colon just before bullet-list much.