docs: tweak CLI argument help texts #4659

pzhlkj6612 · 2022-07-17T17:53:46Z

Hi! This PR contains the re-implement of 1e12d02 in #4618 . The comparison are as follows.

1. plugins.nicolive: docs: apply bold style to "--timeshift-offset"

Commit: cfe5b41

Original:

--niconico-timeshift-offset [HH:]MM:SS#

Amount of time to skip from the beginning of a stream. Default is 00:00:00.

New:

--niconico-timeshift-offset [HH:]MM:SS#

Amount of time to skip from the beginning of a stream.

Default is: 00:00:00.

2. docs: use valid or full-length options to create links

Commit: b1c7ac7

Original:

$ streamlink --help | grep --before-context=1 -e 'IPv4 only'
  -4, --ipv4
    Resolve address names to IPv4 only. This option overrides :option:`-6`.

New:

$ streamlink --help | grep --before-context=1 -e 'IPv4 only'
  -4, --ipv4
    Resolve address names to IPv4 only. This option overrides --ipv6.

3. docs: use bulleted list to organize content

Commit: 0ae409e

Original:

--hls-playlist-reload-time TIME#
Set a custom HLS playlist reload time value, either in seconds or by using one of the following keywords:
segment: The duration of the last segment in the current playlist
live-edge: The sum of segment durations of the live edge value minus one
default: The playlist's target duration metadata

--fs-safe-rules#
These characters are replaced with an underscore for the rules in use:
POSIX  : \x00-\x1F /
Windows: \x00-\x1F \x7F " * / : < > ? \ |

New:

--hls-playlist-reload-time TIME#

Set a custom HLS playlist reload time value, either in seconds or by using one of the following keywords:

segment: The duration of the last segment in the current playlist

live-edge: The sum of segment durations of the live edge value minus one

default: The playlist's target duration metadata

--fs-safe-rules#

These characters are replaced with an underscore for the rules in use:

POSIX: x00-x1F /

Windows: x00-x1F x7F " * / : < > ? |

4. docs: include the option itself in its example

Commit: 9d7e3e3

Original:

--stream-sorting-excludes STREAMS#
For example this will exclude streams from two quality types:
">480p,>medium"

New:

--stream-sorting-excludes STREAMS#
For example this will exclude streams from two quality types:
--stream-sorting-excludes ">480p,>medium"

5. docs: apply option links in indented lines

Commit: 8a0c23f

Original:

VLC specific information:
These variables are accessible in the --title option by adding a backslash in front of the dollar sign which VLC uses as its formatting character.

For example, to put the current date in your VLC window title, the string "\$A" could be inserted inside the --title string.

New:

VLC specific information:
These variables are accessible in the --title option by adding a backslash in front of the dollar sign which VLC uses as its formatting character.

For example, to put the current date in your VLC window title, the string "\$A" could be inserted inside the --title string.

6. docs: add names for special characters

Commit: 1e6217a

Original:

--stream-types TYPES#

--stream-priority TYPES#

A * can be used as a wildcard to match any other type of stream, eg. muxed-stream.

New:

--stream-types TYPES#

--stream-priority TYPES#

An * (asterisk) can be used as a wildcard to match any other type of stream, eg. muxed-stream.

7. docs: adjust string type to avoid doubling symbols

Commit: 72c32f1 (dropped)

No difference between rendered content.

8. docs: use single-backtick inline code block

Commit: 8eda37d (was 0ac38c8) (was d02c81e)

Group 1: webpage

Original:

--fs-safe-rules#

These characters are replaced with an underscore for the rules in use:

POSIX: x00-x1F /

Windows: x00-x1F x7F " * / : < > ? |

New:

--fs-safe-rules#

These characters are replaced with an underscore for the rules in use:

POSIX: \x00-\x1F /

Windows: \x00-\x1F \x7F " * / : < > ? \ |

Group 2: man page

Original:

--locale LOCALE

The preferred locale setting, for selecting the preferred subtitle and audio language.

The locale is formatted as [language_code]_[country_code], eg. en_US or es_ES.

New:

--locale LOCALE

The preferred locale setting, for selecting the preferred subtitle and audio language.

The locale is formatted as [language_code]_[country_code], eg. en_US or es_ES.

Group 3: help content

Original:

$ streamlink --help | grep --before-context=4 --after-context=1 -e 'Valid operators are'
    Uses a filter expression in the format:
    
      [operator]<value>
    
    Valid operators are ``>``, ``>=``, ``<`` and ``<=``. If no operator is specified then
    equality is tested.

New:

$ streamlink --help | grep --before-context=4 --after-context=1 -e 'Valid operators are'
    Uses a filter expression in the format:
    
      [operator]<value>
    
    Valid operators are `>`, `>=`, `<` and `<=`. If no operator is specified then
    equality is tested.

9. docs: put inline code to code blocks in examples

Commit: 4ce3cbc (was 00a9c12) (was b70aaf1)

Original:

--hls-segment-ignore-names NAMES#

A comma-delimited list of segment names that will get filtered out.

Example: --hls-segment-ignore-names 000,001,002

This will ignore every segment that ends with 000.ts, 001.ts and 002.ts

New:

--hls-segment-ignore-names NAMES#

A comma-delimited list of segment names that will get filtered out.

Example: --hls-segment-ignore-names 000,001,002

This will ignore every segment that ends with 000.ts, 001.ts and 002.ts

The "00:00:00" in "Default is 00:00:00." will be in bold style.

Don't show the reStructuredText markup ":option:`foo`" in help content.

Using bulleted lists can avoid unintended syntax highlighting. For "--fs-safe-rules", we will put a part of content into inline code blocks later.

For new users of CLI.

There are some lines starting with two or more spaces contain the options should be links. To achieve it, the following types of lines should not be processed: - Starting with two or more spaces followed by a "%(prog)s"; - Starting with two or more spaces followed by a full-length option; - Starting with an "Example: ".

bastimeyer · 2022-07-17T19:06:24Z

Thanks for the PR. I'll take a closer look at the changes later. Most of it looks fine, but there's at least one change which I don't agree with.

pzhlkj6612 · 2022-07-18T03:16:39Z

Hi @bastimeyer , thanks for your reply.

Most of it looks fine, but there's at least one change which I don't agree with.

I guess the change is "docs: adjust string type to avoid doubling symbols" (72c32f1) . To display "\$A" correctly, I made this change during development, but now it looks a bit wrong and confusing, at least in my view. I'll check it later, so now switch this PR to a draft.

bastimeyer · 2022-07-18T06:32:41Z

I guess the change is "docs: adjust string type to avoid doubling symbols"

Yes. Strings should not get unnecessarily concatenated. This is very confusing to read, especially if you're mixing f-strings with normal strings.

pzhlkj6612 · 2022-07-18T16:02:58Z

Force-pushed what:

"docs: adjust string type to avoid doubling symbols" (72c32f1) has been dropped.
The fix about \$A has been put into 0ac38c8 .

pzhlkj6612 · 2022-07-18T16:08:57Z

I just discovered that "docs: use single-backtick inline code block" (0ac38c8 , or the old commit d02c81e) has fixed a wrong style about backslashes introduced by "docs: use single-backtick inline code block" (0ae409e). Here is the comparison.

Before 0ae409e :

Man page:

$ man ./docs/_build/man/streamlink.1 | grep --after-context=4 -e 'These characters are replaced with'
              These characters are replaced with an underscore for the rules in use:

                 POSIX  : \x00-\x1F /
                 Windows: \x00-\x1F \x7F " * / : < > ? \ |

Webpage:

These characters are replaced with an underscore for the rules in use:
POSIX  : \x00-\x1F /
Windows: \x00-\x1F \x7F " * / : < > ? \ |

After 0ae409e :

Man page:

$ man ./docs/_build/man/streamlink.1 | grep --after-context=4 -e 'These characters are replaced with'
              These characters are replaced with an underscore for the rules in use:

              • POSIX: x00-x1F /

              • Windows: x00-x1F x7F " * / : < > ? |

Webpage:

These characters are replaced with an underscore for the rules in use:

POSIX: x00-x1F /

Windows: x00-x1F x7F " * / : < > ? |

pzhlkj6612 · 2022-07-18T16:13:41Z

Hi, @bastimeyer , all of my changes are ready to be reviewed.

In addition, thank you for rewriting the PR title. Composing a short but clear title is an art.

bastimeyer

Had a deeper look at the changes. Everything's looking fine, thanks.

One minor detail however is how the Example: ... and Examples:\n ... sections get rendered in the man page. Since you're now applying inline code after Example: , stuff gets rendered as highlighted text, whereas the block text does not. That seems to be an issue with Sphinx though, and this can be ignored. Doesn't matter much anyway.

There's also one tiny issue with an unnecessary non-capture group in one of the new regexes, but it's pretty much irrelevant. If you want to fix it, you can do it before this gets merged.

diff --git a/docs/ext_argparse.py b/docs/ext_argparse.py
index 55732fab..2066e57e 100644
--- a/docs/ext_argparse.py
+++ b/docs/ext_argparse.py
@@ -26,7 +26,7 @@ _option_re = re.compile(r"(?:^|(?<=\s))(--\w[\w-]*\w)\b")
 _prog_re = re.compile(r"%\(prog\)s")
 _percent_re = re.compile(r"%%")
 _cli_metadata_variables_section_cross_link_re = re.compile(r"the \"Metadata variables\" section")
-_inline_code_block_re = re.compile(r"(?<!`)`((?:[^`])+?)`")
+_inline_code_block_re = re.compile(r"(?<!`)`([^`]+?)`")
 _example_inline_code_block_re = re.compile(r"(?<=^Example: )(.+)$", re.MULTILINE)

pzhlkj6612 · 2022-07-19T17:39:36Z

Thank you, @bastimeyer .

What do you think about the new commit "docs: highlight inline code blocks in single-line examples" (e3dba12)?

bastimeyer · 2022-07-19T18:12:39Z

Please squash 364821b into 0ac38c8. PRs should not include commits which fix other commits in the same PR.

IMO, e3dba12 is unnecessary, since all it does is highlight quoted shell arguments in example texts which don't actually have to be quoted. The custom role adds unnecessary complexity.

This will make the documentation more clear and informative both on the rendered webpages and in the manpage as well as the "--help" content. - On webpages, we will get inline code blocks; - In the manpage, we will get emphasized words (bold); - In the help content, we will get words enclosed in single backticks. This will help us remove reStructuredText markups from the docs. About "\$A": "\\$A" has been put into a code block, so the single backslash will be displayed correctly in the help content. For rendered docs, escaping backslashes is now no longer required since we did it automatically. --- A useless non-capturing group has been removed as per the suggestion: #4659 (review) Thus, Co-authored-by: bastimeyer <mail@bastimeyer.de>

Only apply to the line starts with "^Example: ".

pzhlkj6612 · 2022-07-20T15:57:34Z

Force-pushed what:

"docs: highlight inline code blocks in single-line examples" (e3dba12) has been dropped due to unnecessary complexity.
"docs: remove a useless non-capturing group" (364821b) has been combined with "docs: use single-backtick inline code block" (0ac38c8) because we should keep the git history clear. Now the commit is 8eda37d .

This will make the documentation more clear and informative both on the rendered webpages and in the manpage as well as the "--help" content. - On webpages, we will get inline code blocks; - In the manpage, we will get emphasized words (bold); - In the help content, we will get words enclosed in single backticks. This will help us remove reStructuredText markups from the docs. About "\$A": "\\$A" has been put into a code block, so the single backslash will be displayed correctly in the help content. For rendered docs, escaping backslashes is now no longer required since we did it automatically. --- A useless non-capturing group has been removed as per the suggestion: #4659 (review) Thus, Co-authored-by: bastimeyer <mail@bastimeyer.de>

bastimeyer · 2022-07-20T22:03:03Z

Thanks

This will make the documentation more clear and informative both on the rendered webpages and in the manpage as well as the "--help" content. - On webpages, we will get inline code blocks; - In the manpage, we will get emphasized words (bold); - In the help content, we will get words enclosed in single backticks. This will help us remove reStructuredText markups from the docs. About "\$A": "\\$A" has been put into a code block, so the single backslash will be displayed correctly in the help content. For rendered docs, escaping backslashes is now no longer required since we did it automatically. --- A useless non-capturing group has been removed as per the suggestion: streamlink#4659 (review) Thus, Co-Authored-By: bastimeyer <mail@bastimeyer.de>

This will make the documentation more clear and informative both on the rendered webpages and in the manpage as well as the "--help" content. - On webpages, we will get inline code blocks; - In the manpage, we will get emphasized words (bold); - In the help content, we will get words enclosed in single backticks. This will help us remove reStructuredText markups from the docs. About "\$A": "\\$A" has been put into a code block, so the single backslash will be displayed correctly in the help content. For rendered docs, escaping backslashes is now no longer required since we did it automatically. --- A useless non-capturing group has been removed as per the suggestion: streamlink#4659 (review) Thus, Co-authored-by: bastimeyer <mail@bastimeyer.de>

pzhlkj6612 added 6 commits July 17, 2022 15:49

plugins.nicolive: docs: apply bold style to "--timeshift-offset"

cfe5b41

The "00:00:00" in "Default is 00:00:00." will be in bold style.

docs: use valid or full-length options to create links

b1c7ac7

Don't show the reStructuredText markup ":option:`foo`" in help content.

docs: use bulleted list to organize content

0ae409e

Using bulleted lists can avoid unintended syntax highlighting. For "--fs-safe-rules", we will put a part of content into inline code blocks later.

docs: include the option itself in its example

9d7e3e3

For new users of CLI.

docs: add names for special characters

1e6217a

bastimeyer added documentation CLI labels Jul 17, 2022

pzhlkj6612 marked this pull request as draft July 18, 2022 03:16

bastimeyer changed the title docs: use single-backtick codeblocks to protect examples and special characters; fix font styles; fix option links; add bulleted lists; add the option itself to the example; add names for special characters docs: tweak CLI argument help texts Jul 18, 2022

pzhlkj6612 marked this pull request as ready for review July 18, 2022 16:13

bastimeyer approved these changes Jul 18, 2022

View reviewed changes

pzhlkj6612 marked this pull request as draft July 19, 2022 02:09

pzhlkj6612 marked this pull request as ready for review July 19, 2022 17:39

pzhlkj6612 marked this pull request as draft July 20, 2022 01:26

pzhlkj6612 and others added 2 commits July 20, 2022 15:32

docs: put inline code to code blocks in examples

4ce3cbc

Only apply to the line starts with "^Example: ".

pzhlkj6612 marked this pull request as ready for review July 20, 2022 16:00

pzhlkj6612 requested a review from bastimeyer July 20, 2022 16:00

bastimeyer merged commit 1741c59 into streamlink:master Jul 20, 2022

pzhlkj6612 deleted the docs-style-options-codeblocks-enhancement branch October 30, 2022 03:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: tweak CLI argument help texts #4659

docs: tweak CLI argument help texts #4659

Uh oh!

pzhlkj6612 commented Jul 17, 2022 •

edited

Loading

Uh oh!

bastimeyer commented Jul 17, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

bastimeyer commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

bastimeyer left a comment

Uh oh!

pzhlkj6612 commented Jul 19, 2022

Uh oh!

bastimeyer commented Jul 19, 2022

Uh oh!

pzhlkj6612 commented Jul 20, 2022

Uh oh!

bastimeyer commented Jul 20, 2022

Uh oh!

Uh oh!

Uh oh!

docs: tweak CLI argument help texts #4659

docs: tweak CLI argument help texts #4659

Uh oh!

Conversation

pzhlkj6612 commented Jul 17, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. plugins.nicolive: docs: apply bold style to "--timeshift-offset"

2. docs: use valid or full-length options to create links

3. docs: use bulleted list to organize content

4. docs: include the option itself in its example

5. docs: apply option links in indented lines

6. docs: add names for special characters

7. docs: adjust string type to avoid doubling symbols

8. docs: use single-backtick inline code block

Group 1: webpage

Group 2: man page

Group 3: help content

9. docs: put inline code to code blocks in examples

Uh oh!

bastimeyer commented Jul 17, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

bastimeyer commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

pzhlkj6612 commented Jul 18, 2022

Uh oh!

bastimeyer left a comment

Choose a reason for hiding this comment

Uh oh!

pzhlkj6612 commented Jul 19, 2022

Uh oh!

bastimeyer commented Jul 19, 2022

Uh oh!

pzhlkj6612 commented Jul 20, 2022

Uh oh!

bastimeyer commented Jul 20, 2022

Uh oh!

Uh oh!

pzhlkj6612 commented Jul 17, 2022 •

edited

Loading