Working on docs, closes #447

CONTRIBUTING.md

@@ -17,16 +17,17 @@ It is also recommended to take a look at these resources:
 - List of `flake8` [extensions](https://github.com/DmytroLitvinov/awesome-flake8-extensions)
 
 
-## API Reference
+## Developer's documentation
 
-Make sure that you are familiar with [our API](https://wemake-python-styleguide.readthedocs.io/en/latest/pages/api.html).
+Make sure that you are familiar with [developer's documentation](https://wemake-python-styleguide.readthedocs.io/en/latest/pages/api.html).
 
 That's a main starting point to the future development.
+You can jump start into the development of new rules by reading ["Creating a new rule tutorial"](https://wemake-python-styleguide.readthedocs.io/en/latest/pages/tutorial.html).
 
 
 ## Dependencies
 
-We use `poetry` to manage the [dependencies](https://github.com/sdispater/poetry).
+We use [`poetry`](https://github.com/sdispater/poetry) to manage the dependencies.
 
 To install them you would need to run `install` command:
 

README.md

@@ -80,7 +80,7 @@ You can find all error codes and plugins [in the docs](https://wemake-python-sty
 
 We are *not* planning to do the following things:
 
-0. Assume or check types, use `mypy` instead
+0. Assume or check types, use [`mypy`](https://github.com/python/mypy) instead
 1. Reformat code, since we believe that developers should do that
 2. Check for `SyntaxError` or exceptions, write tests instead
 3. Appeal to everyone, this is **our** linter. But, you can [switch off](https://wemake-python-styleguide.readthedocs.io/en/latest/pages/usage.html#ignoring-violations) any rules that you don't like

docs/index.rst

@@ -12,7 +12,7 @@
 
 .. toctree::
   :maxdepth: 2
-  :caption: API:
+  :caption: Developer's guide:
   :hidden:
 
   pages/api.rst

wemake_python_styleguide/checker.py

@@ -61,7 +61,7 @@
 @types.final
 class Checker(object):
     """
-    Main checker class.
+    Implementation of :term:`checker`.
 
     See also:
         http://flake8.pycqa.org/en/latest/plugin-development/index.html
@@ -70,9 +70,9 @@ class Checker(object):
         name: required by the ``flake8`` API, should match the package name.
         version: required by the ``flake8`` API, defined in the packaging file.
         config: custom configuration object used to provide and parse options:
-            :py:`wemake_python_styleguide.options.config.Configuration`.
+            :class:`wemake_python_styleguide.options.config.Configuration`.
         options: option structure passed by ``flake8``:
-            :py:`wemake_python_styleguide.types.ConfigurationOptions`.
+            :class:`wemake_python_styleguide.types.ConfigurationOptions`.
         visitors: :term:`preset` of visitors that are run by this checker.
 
     """

wemake_python_styleguide/visitors/base.py

@@ -42,8 +42,8 @@
 It is highly unlikely that you will need two parameters at the same time.
 See :ref:`tutorial` for more information about choosing a correct base class.
 
-Coventions
-~~~~~~~~~~
+Conventions
+~~~~~~~~~~~
 
 Then you will have to write logic for your visitor.
 We follow these conventions:
@@ -64,13 +64,17 @@
 
 import ast
 import tokenize
-from typing import List, Sequence, Type
+from typing import TYPE_CHECKING, List, Sequence, Type
 
 from wemake_python_styleguide import constants
 from wemake_python_styleguide.logics.filenames import get_stem
 from wemake_python_styleguide.types import ConfigurationOptions, final
 from wemake_python_styleguide.violations.base import BaseViolation
 
+if TYPE_CHECKING:
+    # Using this hack to remove circular imports
+    from wemake_python_styleguide.checker import Checker  # noqa: Z435
+
 
 class BaseVisitor(object):
     """
@@ -79,7 +83,8 @@ class BaseVisitor(object):
     Attributes:
         options: contains the options objects passed and parsed by ``flake8``.
         filename: filename passed by ``flake8``, each visitor has a file name.
-        violations: list of violations for the specific visitor.
+        violations: list of :term:`violations <violation>`
+            for the specific visitor.
 
     """
 
@@ -94,12 +99,15 @@ def __init__(
         self.violations: List[BaseViolation] = []
 
     @classmethod
-    def from_checker(cls: Type['BaseVisitor'], checker) -> 'BaseVisitor':
+    def from_checker(
+        cls: Type['BaseVisitor'],
+        checker: 'Checker',
+    ) -> 'BaseVisitor':
         """
         Constructs visitor instance from the checker.
 
         Each unique visitor class should know how to construct itself
-        from the ``checker`` instance.
+        from the :term:`checker` instance.
 
         Generally speaking, each visitor class needs to eject required
         parameters from checker and then run
@@ -178,6 +186,10 @@ class BaseFilenameVisitor(BaseVisitor):
     Abstract base class that allows to visit and check module file names.
 
     Has ``visit_filename()`` method that should be defined in subclasses.
+
+    Attributes:
+        stem: the last part of the filename. Does not contain extension.
+
     """
 
     stem: str
@@ -248,6 +260,8 @@ def visit(self, token: tokenize.TokenInfo) -> None:
 
         Does nothing if handler for any token type is not defined.
 
+        Inspired by ``NodeVisitor`` class.
+
         See also:
             https://docs.python.org/3/library/tokenize.html