docs: add dedicated metadata variables section #4207
Conversation
- add dedicated metadata variables section to the CLI docs - rewrite --title help text - update --output, --record and --record-and-pipe help texts
bastimeyer
force-pushed
the
docs/metadata-vars
branch
from
87c0d7e
to
e712ff2
Compare
|
|
||
| Example: | ||
|
|
||
| %(prog)s --record-and-pipe "~/recordings/{author}/{category}/{id}-{time:%Y%m%d%H%M%S}.ts" <URL> [STREAM] |
There was a problem hiding this comment.
I don't know if it's a Netlify thing only, and it's certainly very minor, but I see that different CSS is applied to and in --record-and-pipe here. I thought it was eyes at first! Technically, that's nothing to do with the content of this PR though, but it's just something I noticed and thought I would mention.
Specifically, the surrounding text is colour #d0d0d0, while and is colour #6ab825.
There was a problem hiding this comment.
It's because of the custom argparse extension which tries to build ReST from certain text patterns used in the argparse help texts:
streamlink/docs/ext_argparse.py
Line 22 in 3309ed0
streamlink/docs/ext_argparse.py
Lines 72 to 73 in 3309ed0
Text indented by at least 2 spaces gets turned into a literal-block which then gets highlighted by Sphinx automatically when there's no block type specified:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
There are a couple of other examples in the docs where it's parsing it incorrectly, but we can't use full ReST syntax in the argparse help texts because of the --help output and the man page, so it's a bit difficult to fix this.
There was a problem hiding this comment.
It's so trivial it was not worth worrying about anyway, but more so if the fix is tricky. I just wasn't sure if it had been noticed before.
- add dedicated metadata variables section to the CLI docs - rewrite --title help text - update --output, --record and --record-and-pipe help texts
ref #4205
This moves the metadata variables from the argparse help texts into the CLI docs. This unfortunately means that the argparse help texts can't link to the metadata variables section. At least I don't know how to do this.
It also means that the metadata vars are currently not part of the man page anymore, because the man page only includes the argparse stuff and not the entire CLI document (because we don't want the CLI tutorial in the man page). This could be fixed in the future by splitting up the sections into their own documents and including those in the CLI document and man page.
https://deploy-preview-4207--streamlink.netlify.app/cli.html#metadata-variables
https://deploy-preview-4207--streamlink.netlify.app/cli.html#cmdoption-title