docs: replace plugin matrix #4374
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The metadata is copied from the documentation's plugin_matrix, which is going to be replaced by a sphinx extension which parses the metadata in each plugin file and dynamically generates the plugins document. Metadata tests will be added with sphinx extension. TODO: - Add $description metadata tags. Some of the plugin descriptions can be found in the git history, while others have to be retrieved from issues and pull requests on GitHub, or they have to be looked up. - Add URLs to metadata which were previously missing in the plugin matrix due to space constraints (see the matcher regexes).
and fix links in other documents
|
Not sure why the preview doesn't include any plugin arguments. |
Implement custom "plugins" sphinx extension which parses metadata from plugin files and which outputs a list of plugins with datalists that include the annotated metadata in addition to plugin arguments and links to plugin files + issues on GitHub. Add plugin metadata linting tests and remove old plugin matrix tests.
bastimeyer
force-pushed
the
plugins/metadata
branch
from
a4a69af to
ca9755b
Compare
|
Instead of bumping the python version on netlify, I made the AST parsing in the sphinx extension python 3.6 and 3.7 compatible. This now correctly builds with plugin arguments. I've also updated the developing page in the docs. |
|
Finally had some time to review the various commits this evening. Looks good and the format makes sense to me! |
Billy2011
added a commit
to Billy2011/streamlink-27
that referenced
this pull request
Mar 5, 2022
Billy2011
added a commit
to Billy2011/streamlink-27
that referenced
this pull request
Mar 5, 2022
Implement custom "plugins" sphinx extension which parses metadata from plugin files and which outputs a list of plugins with datalists that include the annotated metadata in addition to plugin arguments and links to plugin files + issues on GitHub. Add plugin metadata linting tests and remove old plugin matrix tests.
Billy2011
added a commit
to Billy2011/streamlink-27
that referenced
this pull request
Mar 5, 2022
Implement custom "plugins" sphinx extension which parses metadata from plugin files and which outputs a list of plugins with datalists that include the annotated metadata in addition to plugin arguments and links to plugin files + issues on GitHub. Add plugin metadata linting tests and remove old plugin matrix tests.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Resolves #4369
This replaces the plugin matrix with a dynamically generated list of plugins via a custom sphinx extension that parses a mandatory header comment in each plugin. See #4369 for the motivation of this.
First commit
This adds the metadata header comment to each plugin. The data was copied from the old plugin matrix and in some cases adjusted a bit. Some plugins received additional/missing data, like zattoo for example, where URLs were copied from the plugin matcher regex. In case of zatto, this was very obvious, because of the large number of URLs and the previous notes. It's very likely that there are similar plugins that did not get updated. This can be fixed in the future.
The metadata currently also does not include any
$descriptiontags. These need to be added later and then be made mandatory once every plugin has got one. Some of the plugin descriptions can be found in each plugin's git history, because lots of old header comments got removed in the past. Checking GitHub issues and pull requests can also help.The metadata format is very strict and gets linted via the tests added in the third commit.
Second commit
This renames the doc's
plugin_matrixpage topluginsand will thus make old links go 404 once merged. Since the plugin data is not represented as a table anymore, it doesn't really make sense calling the menu "plugin_matrix". The link in the main menu has always been called "Plugins" because it refers to the page's top header text.Third commit
This finally removes the plugin matrix and replaces it with the new sphinx extension, and it also adds tests which lint the plugin files and their strict metadata format.
The sphinx extension does not lint/validate the metadata and relies on the tests for validity. Since we're building docs and are running tests in parallel, this could cause confusion, but I don't think it's a problem. The tests are all atomic and parametrized, so any errors when something gets changed or added should be trivial to resolve, and it doesn't matter if the docs fail or produce broken output.
Plugin arguments which get read from each plugin's AST are also not 100% safe, as it's just a simple lexical analysis. Extending it with more validations where the plugin arguments are defined (and that the imports are actually correct) would be possible, but it would bloat up the extension's logic by quite a bit and it's not worth it. This issue shouldn't matter too much, as plugins get reviewed before merging anyway.
Fourth commit
Updates the "developing" docs page.