Improve documentation #226
Closed
Conversation
This file contains 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
alrra
reviewed
May 23, 2017
| @@ -1 +1,22 @@ | |||
| # Developer guide | |||
|
|
|||
| Sonar was designed with extensibility in mind. There are 3 main concepts that a | |||
| sonar developer needs to know about: | |||
There was a problem hiding this comment.
Let's just use developer instead of sonar developer.
| Sonar was designed with extensibility in mind. There are 3 main concepts that a | ||
| sonar developer needs to know about: | ||
|
|
||
| * `rule`: It is a test that is run on an asset (website, HTML file, image, |
| use them without having to do a Pull Request to the main project. They can even | ||
| be distributed as `npm` packages. | ||
|
|
||
| Even though sonar is developed using [TypeScript](http://www.typescriptlang.org/), |
|
|
||
| Any developer can create their own `rule`s, `collector`s, and/or `formatter`s and | ||
| use them without having to do a Pull Request to the main project. They can even | ||
| be distributed as `npm` packages. |
There was a problem hiding this comment.
[`npm`](https://www.npmjs.com/)
|
|
||
| To create a new rule you just need to: | ||
|
|
||
| * Create a `new-rule.ts` file in a folder with the same name of the rule |
| Getting started with sonar's CLI is really easy. First you need to install it: | ||
|
|
||
| ```bash | ||
| npm install -g sonarwhal@sonar |
| ``` | ||
|
|
||
| This command will start a wizard that will ask you a series of questions (what | ||
| collector to use, what formatter, what rules, etc.). Answer them and you will |
| [rules documentation](./rules/). | ||
|
|
||
| Sometimes you want to enable a rule but not for all the domains a website | ||
| depends on. For example, if your website loads some external library from a cdn |
| The value of the property has to be an array of strings where the strings can be: | ||
|
|
||
| * `*` if you want to ignore all rules for the given domain. | ||
| * A rule id with the rules to ignore. |
There was a problem hiding this comment.
the ID of the rule to be ignored
| A `formatter` takes the results of executing all the rules and transforms them to | ||
| be consumed by the user. A `formatter` can output the results via the `console` in | ||
| different formats, a `JSON` file, `XML`, etc. | ||
| Please reach [the current list of supported `formatter`s](./formatters/) to know |
alrra
reviewed
May 23, 2017
| @@ -1,5 +1,7 @@ | |||
| # Rules | |||
|
|
|||
| > The rules should be groupped by category | |||
alrra
reviewed
May 23, 2017
| * `json`: Will do a `JSON.stringify()` of the results so the output will not be | ||
| user friendly: | ||
|
|
||
| > PICTURE WITH THE OUTPUT HERE!! |
There was a problem hiding this comment.
@molant Added text output for now. We can also add images, but using text is easier to update, also more accessible I guess, etc.
There was a problem hiding this comment.
But we will miss the colors and formatting. We should use alt for accessibility.
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.
Fix #162
Work on #225