docs: split CLI into submenus #4415
Conversation
- move any sections except for "Command-line usage" (argparse content) into separate, logical submenus - rename certain section headers - fix all references - slightly rephrase certain things
|
"Command-line usage" gets linked twice on the index page due to the toctree issue mentioned above, but that can be ignored. |
|
Thanks for the documentation reorg, the cli docs are much clearer with the new subsections. I'll take this opportunity to ask again (#117 wow... 5 years passed by already :-) ) for improving documentation for (casual?) developers of plugins. To be honest, I tried to make a simple one for some sites I use often, or improve generic when it fails, but I found that I spent a lot of time doing reverse engineering and fiddling to try to get a solution, and found myself discouraged and jump instead to find the stream manually with the browser console in the end. So if it's possible to add a section for plugin development (ie under sideloading docs category?), and take an stable plugin and be very very verbose on commenting it (ie mandatory functions, input params, expected return information, error handling, high level interaction with the core modules, etc etc) I think there will be more and more participation of casual devs that may use streamlink as a easily customizable solution for those rebel sites :-) I know a major improvement to the plugin loading mechanism is being worked on (#3814) so maybe it will be a good opportunity to help improve the plugin dev docs as well? Please please please don't misinterpret me, I'm a happy user of streamlink and grateful to you all for your dedication the the app, just want to get my hands on it from time to time for the sake of the mental challenge, and probably some others are on the same page as me. Thanks again all. |
This is exactly what a plugin implementation is, reverse engineering and fiddling, trying to get the stream URL which can then be plugged into the constructor method of the various stream implementations supported by Streamlink, like HLS, DASH, etc. There is no generic solution which could be documented, because it varies every single time. One needs to at least have a basic understanding of web standards, as I've already explained in another issue. Having a documented example plugin doesn't make much sense, because it would almost never translate into any real plugin implementations and it would become outdated eventually without someone spending additional maintenance time on it which I think is unnecessary. The Streamlink APIs are all there for you to read and study, and written test cases are the best examples with real usage data. If someone is dedicated enough, learning from existing code instead of bad and potentially outdated documentation is the much better way. If one wants to submit a new plugin but is unsure if it has been done right, then this is no problem at all and reviews from other devs will most certainly solve all the issues and questions. For private third party plugin implementations, I honestly don't care if Streamlink's lack of proper documentation causes problems for others. All the Streamlink utility functions are optional anyway. And the discussion forum is always there for questions. The potential of having more plugin submissions if there were better documentation is also questionable IMO. But if someone feels like writing thorough and up2date documentation in order to help the project and attract new contributors, then please submit a pull request. So far, nobody has been willing to spend any time on it (for five years). |
There was a problem hiding this comment.
🤦♂️ Thought I marked this as approved when I looked at it a few days ago. I'm not concerned about the ToC issue nor am I concerned about breaking any existing links. It happens and the split is absolutely worth it for how much easier it makes doc navigation.
into separate, logical submenus
The motivation for this is that the CLI docs page is way too large and that the actual CLI informations (argparse data) are buried below the tutorial, config file, plugin-sideloading, proxy, streaming-protocol, metadata, and other plugin related sections. This is especially bad, because the tutorial is meant to be read once for new users. For users who are not new, this is distracting and annoying.
Adding more plugin specific docs (eg. adding Twitch low latency docs) to the current monolithic page would make this even more problematic.
I've therefore split the CLI docs into multiple logical submenus, rearranged and rephrased some stuff.
New content and other improvements can be done afterwards.
One minor issue I didn't manage to overcome was the
toctreeand theselfreference. It's currently impossible to list sections of the own document (cli.rst- which includes the "Command-line usage" section), so it's a little bit confusing, as it doesn't link to the actual subsection. See sphinx-doc/sphinx#2103.This will break any existing links on this issue tracker or anywhere else that are not argparse related. I don't think is much of an issue though. The most important links, like anchors to argparse args will remain the same. And the man page also won't be affected by this change.
My aim is to split the changelog in a similar way next, by major release version number. The changelog is currently a symlink to the
CHANGELOG.mdfile at the root dir, so I'm not sure yet what the best solution for this will be.