README: Add installation and linter documentation.

Update documentation on how to use Zulint. Describe RuleList,
Rule and how to properly write them. Recommend pip for installation.

Author: amanagr

README.md

@@ -93,17 +93,144 @@ run the hook from outside Vagrant).
 
 ## Adding zulint to a codebase
 
-TODO.  Will roughly include `pip install zulint`, copying an example
-`lint` script, and adding your rules.
+TODO: Make a pypi release
 
+Add `zulint` to your codebase requirements file or just do:
+
+```
+pip install zulint
+```
+
+See [example-lint](./example-lint) file for a simple example of adding zulint to
+your codebase. For a more advanced usage example, you can look at
+[Zulip's linter](https://github.com/zulip/zulip/blob/master/tools/lint).
+
+**NOTE**
+
+* Remember to mark your lint file executable using:
+
+```bash
+> chmod +x <YOUR LINT FILE>
+```
+
+* Add `<YOUR LINTER VARIABLE NAME>.do_lint()` add the end of your lint file.
 
 ## Adding third-party linters
 
-TODO: Document the linter_config API.
+First import the `LinterConfig` and initialize it with default arguments.
+You can then use the `external_linter` method to register the linter.
+
+eg:
+
+```python
+import argparse
+from zulint.command import add_default_linter_arguments, LinterConfig
+parser = argparse.ArgumentParser()
+# Add custom parser arguments here.
+
+add_default_linter_arguments(parser)
+args = parser.parse_args()
+
+linter_config = LinterConfig(args)
+
+# Add your external litner:
+linter_config.external_linter('eslint', ['node', 'node_modules/.bin/eslint',
+                                          '--quiet', '--cache', '--ext', '.js,.ts'], ['js', 'ts'],
+                              fix_arg='--fix',
+                              description="Standard JavaScript style and formatting linter"
+                              "(config: .eslintrc).")
+
+linter_config.do_lint()
+```
+
+Please make sure external linter (here `eslint`) is accessible via bash or in the
+virtual env where this linter will run.
 
 ## Writing custom rules
 
-TODO: Document all the features of the `RuleList` and `custom_check` system.
+You can write your own custom rules for any language using regular expression
+in zulint. Doing it is very simple and there are tons of examples available
+in [Zulip's custom_check.py file](https://github.com/zulip/zulip/blob/master/tools/linter_lib/custom_check.py).
+
+In the [above example](#adding-third-party-linters) you can add custom rules via `@linter_config.lint` decorator.
+For eg:
+
+```python
+
+from zulint.custom_rules import RuleList
+
+@linter_config.lint
+def check_custom_rules():
+    # type: () -> int
+    """Check trailing whitespace for specified files"""
+    trailing_whitespace_rule = RuleList(
+        langs=file_types,
+        rules=[{
+            'pattern': r'\s+$',
+            'strip': '\n',
+            'description': 'Fix trailing whitespace'
+        }]
+    )
+    failed = trailing_whitespace_rule.check(by_lang, verbose=args.verbose)
+    return 1 if failed else 0
+```
+
+#### RuleList
+A new custom rule is defined via the `RuleList` class. `RuleList` takes the following arguments:
+
+```python
+langs                             # The languages this rule will run on. eg: ['py', 'bash']
+rules                             # List of custom `Rule`s to run. See definition of Rule below for more details.
+max_length                        # Set a max length value for each line in the files. eg: 79
+length_exclude                    # List of files to exclude from `max_length` limit. eg: ["README"]
+shebang_rules                     # List of shebang `Rule`s to run in `langs`. Default: []
+exclude_files_in                  # Directory to exclude from all rules. eg: 'app/' Default: None
+exclude_max_length_fns            # List of file names to exclude from max_length limit. eg: [test, example] Defautl: []
+exclude_max_length_line_patterns  # List of line patterns to exclude from max_length limit. eg: ["`\{\{ api_url \}\}[^`]+`"]
+```
+
+#### Rule
+A rule is a python dictionary containing regular expression,
+which will be run on each line in the `langs`' files specified in the `RuleList`.
+It has a lot of additional features which you can use to run the pattern in
+specific areas of your codebase.
+
+Find below all the keys that a `Rule` can have along with the
+type of inputs they take.
+
+```python
+Rule = TypedDict("Rule", {
+    "bad_lines": List[str],
+    "description": str,
+    "exclude": Set[str],
+    "exclude_line": Set[Tuple[str, str]],
+    "exclude_pattern": str,
+    "good_lines": List[str],
+    "include_only": Set[str],
+    "pattern": str,
+    "strip": str,
+    "strip_rule": str,
+}, total=False)
+```
+
+* `pattern` is your regular expression to be run on all the eligible lines (i.e. lines which haven't been excluded by you).
+* `description` is the message that will be displayed if a pattern match is found.
+* `good_lines` are the list of sample lines which shouldn't match the pattern.
+* `bad_lines` are like `good_lines` but they match the pattern.
+
+**NOTE**: `patten` is run on `bad_lines` and `good_lines` and you can use them as an example to tell the developer
+      what is wrong with their code and how to fix it.
+
+* `exclude` List of folders to exclude.
+* `exclude_line` Tuple of filename and pattern to exclude from pattern check.
+eg:
+
+```python
+('zerver/lib/actions.py', "user_profile.save()  # Can't use update_fields because of how the foreign key works.")`
+```
+
+* `exclude_pattern`: pattern to exclude from the matching patterns.
+* `include_only`: `pattern` is only run on these files.
 
 ## Development Setup
 
@@ -112,5 +239,5 @@ Run the following commands in a terminal to install zulint.
 git clone [email protected]:zulip/zulint.git
 python3 -m venv zulint_env
 source zulint_env/bin/activate
-python3 setup.py install
+pip install -e .
 ```