Provide more comprehensive documentation for static filter list generation
Background
While attempting to integrate static filter lists into Adblock Plus (see https://gitlab.com/adblockinc/ext/adblockplus/adblockplusui/-/issues/1069), I've been struggling with the documentation in various ways.
Furthermore, if consumers are expected to rely on and modify the file generated by npm run subs-init
, they need to have more information about its content.
Use case
Integrate static filter lists into Adblock Plus, as well as keep them up-to-date.
What to change
- Update the README:
- Add CLI usage information (e.g. description, available parameters) about individual scripts for generating static filter lists.
- Clarify purpose and usage of
npm run subs-merge
script, as it's not even used in the example code.
- Clarify purpose and usage of
- Mention changes that need to be made to manifest.json file for Manifest v3:
- Insert manifest file fragment (created by
npm run subs-generate
) under "declarative_net_request" property. - Add "declarativeNetRequest" permission (or possibly even better "declarativeNetRequestWithHostAccess").
- Insert manifest file fragment (created by
- Mention what needs to be done to let EWE know which filter lists there are, so that it can preinstall all necessary default subscriptions on first-run. This may also mean advising consumers not to use
EWE.filters.getRecommended()
anymore. - Fix: Table of content links to h2 headlines are broken.
- Fix: Table of content doesn't include "MV3 subscriptions" section, which mistakenly uses h1 headline.
- Add CLI usage information (e.g. description, available parameters) about individual scripts for generating static filter lists.
- Provide documentation of file format of JSON file that's generated by
npm run subs-init
and ensure that changes to the format are communicated as breaking changes in EWE release notes.
Edited by Thomas Greiner