Improved documentation, made sure that everything can be built

Author: ameshkov

README.md

@@ -1,83 +1,99 @@
-# TSUrlFilter
+# TSUrlFilter libraries
 
-This repo contains typescript packages implementing AdGuard filtering engine.
+This repo contains typescript packages that implement AdGuard filtering engine.
 
-## Packages:
+## Packages
 
-- tsurlfilter
-- tswebextension
-- adguard-api
-- agtree
-- examples/manifest-v2
-- examples/manifest-v3
-- examples/tswebextension-example
-- examples/tswebextension-mv3
+- `tsurlfilter`
+- `tswebextension`
+- `adguard-api`
+- `agtree`
+- `examples/manifest-v2`
+- `examples/manifest-v3`
+- `examples/tswebextension-example`
+- `examples/tswebextension-mv3`
 
 See packages details in `./packages`.
 
 ### TSUrlFilter
 
-TSUrlFilter is a TypeScript library that implements AdGuard's blocking rules logic.
-See details in [`./packages/tsurlfilter`](/packages/tsurlfilter/README.md).
+TSUrlFilter is a TypeScript library that implements AdGuard's blocking rules
+logic. See details in [`./packages/tsurlfilter`][tsurlfilterreadme].
+
+[tsurlfilterreadme]: /packages/tsurlfilter/README.md
 
 ### TSWebExtension
 
-TSWebExtension is a TypeScript library that wraps webextension api for tsurlfilter library. 
-See details in [`./packages/tswebextension`](/packages/tswebextension/README.md).
+TSWebExtension is a TypeScript library that wraps webextension api for the
+tsurlfilter library. See details in
+[`./packages/tswebextension`][tswebextensionreadme].
+
+[tswebextensionreadme]: /packages/tswebextension/README.md
 
 ### AdGuard API
 
-AdGuard API is a TypeScript filtering library that provides filter list management, ad filtering via [@adguard/tswebextension](/packages/tswebextension/README.md).
-See details in [`./packages/adguard-api`](/packages/adguard-api/README.md).
+AdGuard API is a TypeScript filtering library that provides filter list
+management, ad filtering via [@adguard/tswebextension][tswebextensionreadme].
+See details in [`./packages/adguard-api`][adguardapireadme].
 
-### Sample extensions
+[adguardapireadme]: /packages/adguard-api/README.md
 
-Source code of the sample extensions is located in the directory `./packages/examples`.
+### AGTree
 
-To build sample manifest-v2 extension go to the one of the examples and run:
-```
-$ lerna bootstrap && lerna run --scope manifest-v2 build
-```
-Reciprocally with manifest-v3:
-```
-$ lerna bootstrap && lerna run --scope manifest-v3 build
-```
-and
-```
-$ lerna bootstrap && lerna run --scope tswebextension-example build
-``` 
+AGTree is an AST implementation for adguard filtering rules. See details in
+[`./packages/agtree`][agtreereadme].
 
-After that it's ready to be added to Chrome using "Load unpacked" in developer mode.
+[agtreereadme]: /packages/agtree/README.md
 
-To test if this extension works correctly you can use next test pages:
+## Development
 
-Test pages:
--   [Simple rules test](http://testcases.adguard.com/Filters/simple-rules/test-simple-rules.html)
--   [Script rules test](http://testcases.adguard.com/Filters/script-rules/test-script-rules.html)
+Prepare your local environment.
 
+```shell
+# Install dev dependencies and lerna locally.
+yarn install
 
-## Development
+# Prepare and build tswebextension package as they are required for
+# bootstrapping examples.
+npx lerna bootstrap --scope=@adguard/tswebextension --include-dependencies
+npx lerna run build --scope=@adguard/tswebextension
 
-```
-npm install -g lerna
+# Bootstrap all packages.
+npx lerna bootstrap
 ```
 
-```
-lerna bootstrap
-```
+Bootstraps packages in the current repo. Installs all their dependencies and
+linking any cross-dependencies.
 
-Bootstrap the packages in the current repo. Installing all their dependencies and linking any cross-dependencies.
+**Note**: If you want to use another linked packages in monorepo workspace, link
+it in root folder.
 
-**Note**: If you want to use another linked packages in monorepo workspace, link it in root folder
+Runs tests in all packages:
 
-```
-lerna run test
+```shell
+npx lerna run test
 ```
 
-Runs tests in all packages.
+Builds the packages in the current repo:
 
+```shell
+npx lerna run build
 ```
-lerna run build
-```
 
-Builds the packages in the current repo.
+### Sample extensions
+
+Source code of sample extensions can be found in `./packages/examples`.
+
+- `npx lerna run build --scope tswebextension-mv2` - MV2 sample extension.
+- `npx lerna run build --scope tswebextension-mv3` - MV3 sample extension.
+- `npx lerna run build --scope adguard-api-example` - AdGuard API example.
+
+To test if this extension works correctly you can use the following test pages:
+
+Test pages:
+
+- [Simple rules test][testcasessimplerules]
+- [Script rules test][testcasesscriptrules]
+
+[testcasessimplerules]: https://testcases.agrd.dev/Filters/simple-rules/test-simple-rules.html
+[testcasesscriptrules]: https://testcases.agrd.dev/Filters/script-rules/test-script-rules.html