Skip to content

docs: split CLI into submenus #4415

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

Merged
merged 1 commit into from
Apr 2, 2022

Conversation

bastimeyer
Copy link
Member

  • 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

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 toctree and the self reference. 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.md file at the root dir, so I'm not sure yet what the best solution for this will be.

- 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
@bastimeyer
Copy link
Member Author

See https://deploy-preview-4415--streamlink.netlify.app/

@bastimeyer
Copy link
Member Author

"Command-line usage" gets linked twice on the index page due to the toctree issue mentioned above, but that can be ignored.

@WolfganP
Copy link

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.

@bastimeyer
Copy link
Member Author

improving documentation for (casual?) developers of plugins
I spent a lot of time doing reverse engineering and fiddling

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.
#3195 (comment)

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).

@bastimeyer bastimeyer requested a review from gravyboat April 2, 2022 11:54
Copy link
Member

@gravyboat gravyboat left a comment

Choose a reason for hiding this comment

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

🤦‍♂️ 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.

@bastimeyer bastimeyer merged commit 03d1863 into streamlink:master Apr 2, 2022
@bastimeyer bastimeyer deleted the docs/split-cli branch April 2, 2022 19:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants