Version 0.0.11 release

CHANGELOG.md

@@ -17,6 +17,9 @@ There are no new features introduced.
 
 - Introduced the concept of regression testing, see `test/fixtures/regression`
 - Removed `compat.py`
+- Fixes some minor typos, problems, markup inside the docs
+- Adds some new configuration to `sphinx`
+- Changes `sphinx` docs structure a little bit
 
 
 ## Version 0.0.10 aka The Module Reaper

README.md

@@ -11,9 +11,10 @@
 Welcome to the most opinionated linter ever.
 
 `wemake-python-styleguide` is actually just a `flake8` plugin.
-The main goal of this tool is to make our `python` code consistent.
+The main goal of this tool is to make our `python` code
+consistent and to fight the code complexity.
 
-```
+```text
 The Zen of Python, by Tim Peters
 
 Beautiful is better than ugly.

docs/_pages/errors.rst

@@ -1,20 +1,32 @@
 Errors
 ------
 
-.. automodule:: wemake_python_styleguide.errors.base
-   :members:
+General
+~~~~~~~
 
 .. automodule:: wemake_python_styleguide.errors.general
    :members:
 
+Imports
+~~~~~~~
+
 .. automodule:: wemake_python_styleguide.errors.imports
    :members:
 
+Classes
+~~~~~~~
+
 .. automodule:: wemake_python_styleguide.errors.classes
    :members:
 
+Complexity
+~~~~~~~~~~
+
 .. automodule:: wemake_python_styleguide.errors.complexity
    :members:
 
+Modules
+~~~~~~~
+
 .. automodule:: wemake_python_styleguide.errors.modules
    :members:

docs/conf.py

@@ -57,6 +57,11 @@
 
 autodoc_member_order = 'bysource'
 
+autodoc_mock_imports = [
+    'flake8',
+    'typing_extensions',
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -177,6 +182,8 @@
 
 # -- Extension configuration -------------------------------------------------
 
+napoleon_numpy_docstring = False
+
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.

docs/requirements.txt

@@ -6,6 +6,3 @@ sphinxcontrib-napoleon==0.6.1
 sphinx_autodoc_typehints==1.3.0
 recommonmark==0.4.0
 m2r==0.1.15
-
-# In app dependecies (required due to RtD does not support poetry):
-flake8>=3.5,<3.6

wemake_python_styleguide/errors/classes.py

@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
 
 """
-These rules checks that ``class``es are defined correctly.
+These rules checks that ``class`` definitions are correct.
+
+Note:
+
+    Beautiful is better than ugly.
+    Explicit is better than implicit.
+    In the face of ambiguity, refuse the temptation to guess.
+    There should be one-- and preferably only one --obvious way to do it.
 
-Beautiful is better than ugly.
-Explicit is better than implicit.
-In the face of ambiguity, refuse the temptation to guess.
-There should be one-- and preferably only one --obvious way to do it.
 """
 
 from wemake_python_styleguide.errors.base import ASTStyleViolation
@@ -16,7 +19,7 @@ class StaticMethodViolation(ASTStyleViolation):
     """
     This rule forbids to use ``@staticmethod`` decorator.
 
-    Use regular methods, ``classmethods``, or raw functions instead.
+    Use regular methods, ``classmethods`` or raw functions instead.
 
     Note:
         Returns Z300 as error code

wemake_python_styleguide/errors/complexity.py

@@ -8,9 +8,12 @@
 1. Complex code (there are a lof of complexity checks!)
 2. Nested classes, functions
 
-Simple is better than complex.
-Complex is better than complicated.
-Flat is better than nested.
+Note:
+
+    Simple is better than complex.
+    Complex is better than complicated.
+    Flat is better than nested.
+
 """
 
 from wemake_python_styleguide.errors.base import ASTStyleViolation
@@ -24,7 +27,7 @@ class NestedFunctionViolation(ASTStyleViolation):
     However, there are some whitelisted names like,
     see ``NESTED_FUNCTIONS_WHITELIST`` for the whole list.
 
-    We also disallow to nest ``lambda``s.
+    We also disallow to nest ``lambda``.
 
     Example::
 
@@ -94,10 +97,10 @@ def second_function(argument):
 
     In this example we will count as locals only several variables:
 
-    1. `first_var`, because it is assigned inside the function's body
-    2. `second_var`, because it is assigned inside the function's body
-    3. `argument`, because it is reassigned inside the function's body
-    4. `third_var`, because it is assigned inside the function's body
+    1. ``first_var``, because it is assigned inside the function's body
+    2. ``second_var``, because it is assigned inside the function's body
+    3. ``argument``, because it is reassigned inside the function's body
+    4. ``third_var``, because it is assigned inside the function's body
 
     Please, note that `_` is a special case. It is not counted as a local
     variable. Since by design it means: do not count me as a real variable.
@@ -117,7 +120,7 @@ class TooManyArgumentsViolation(ASTStyleViolation):
     """
     This rule forbids to have too many arguments for a function or method.
 
-    This is an indecator of a bad desing.
+    This is an indicator of a bad desing.
     When function requires many arguments
     it shows that it is required to refactor this piece of code.
 
@@ -134,10 +137,12 @@ class TooManyArgumentsViolation(ASTStyleViolation):
 
 class TooManyElifsViolation(ASTStyleViolation):
     """
-    This rule forbids to use many `elif` branches.
+    This rule forbids to use many ``elif`` branches.
 
-    This rule is specifically important, becase many `elif` branches indicate
-    a complex flow in your design: you are reimplementing `switch` in python.
+    This rule is specifically important,
+    because many ``elif`` branches indicate
+    a complex flow in your design:
+    you are reimplementing ``switch`` in python.
 
     There are different design patters to use instead.
 

wemake_python_styleguide/errors/general.py

@@ -1,19 +1,22 @@
 # -*- coding: utf-8 -*-
 
 """
-These rules checks some general rules.
+These rules check some general issues.
 
 Like:
 
-1. Naming
-2. Using some builtins
-3. Using keywords
-4. Working with exceptions
+1. Incorrect naming
+2. Using wrong builtins
+3. Using wrong keywords
+4. Working with exceptions "the bad way"
+
+Note:
+
+    Beautiful is better than ugly.
+    Explicit is better than implicit.
+    In the face of ambiguity, refuse the temptation to guess.
+    There should be one-- and preferably only one --obvious way to do it.
 
-Beautiful is better than ugly.
-Explicit is better than implicit.
-In the face of ambiguity, refuse the temptation to guess.
-There should be one-- and preferably only one --obvious way to do it.
 """
 
 from wemake_python_styleguide.errors.base import ASTStyleViolation
@@ -44,7 +47,7 @@ class WrongKeywordViolation(ASTStyleViolation):
 
 class BareRiseViolation(ASTStyleViolation):
     """
-    This rule forbids using bare `raise` keyword outside of `except` block.
+    This rule forbids using bare ``raise`` keyword outside of ``except`` block.
 
     This may be a serious error in your application,
     so we should prevent that.
@@ -68,10 +71,10 @@ class BareRiseViolation(ASTStyleViolation):
 
 class RaiseNotImplementedViolation(ASTStyleViolation):
     """
-    This rule forbids to use `NotImplemented` error.
+    This rule forbids to use ``NotImplemented`` error.
 
     These two errors have different use cases.
-    Use cases of `NotImplemented` is too limited to be generally available.
+    Use cases of ``NotImplemented`` is too limited to be generally available.
 
     Example::
 
@@ -206,11 +209,11 @@ class WrongModuleMetadataViolation(ASTStyleViolation):
 
 class FormattedStringViolation(ASTStyleViolation):
     """
-    This rule forbids to use `f` strings.
+    This rule forbids to use ``f`` strings.
 
-    `f` strings looses context to often, they are hard to lint.
-    Also, they promote a bad practice: putting a logic into the template.
-    Use `.format()` instead.
+    ``f`` strings looses context too often and they are hard to lint.
+    Also, they promote a bad practice: putting your logic inside the template.
+    Use ``.format()`` instead.
 
     Example::
 
@@ -251,15 +254,15 @@ class EmptyModuleViolation(ASTStyleViolation):
 
 class InitModuleHasLogicViolation(ASTStyleViolation):
     """
-    This rule forbids to have logic inside `__init__` module.
+    This rule forbids to have logic inside ``__init__`` module.
 
-    If you have logic inside the `__init__` module it means several things:
+    If you have logic inside the ``__init__`` module it means several things:
 
     1. you are keeping some outdated stuff there, you need to refactor
     2. you are placing this logic into the wrong file, just create another one
     3. you are doing some dark magic, and you should not do that
 
-    However, we allow to have some contents inside the `__init__` module:
+    However, we allow to have some contents inside the ``__init__`` module:
 
     1. comments, since they are dropped before AST comes in play
     2. docs string, because sometimes it is required to state something

wemake_python_styleguide/errors/imports.py

@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
 
 """
-These rules checks ``import``s to be defined correctly.
+These rules checks ``import`` statements to be defined correctly.
+
+Note:
+
+    Explicit is better than implicit.
+    Flat is better than nested.
+    Sparse is better than dense.
+    Readability counts.
 
-Explicit is better than implicit.
-Flat is better than nested.
-Sparse is better than dense.
-Readability counts.
 """
 
 from wemake_python_styleguide.errors.base import ASTStyleViolation
@@ -114,6 +117,9 @@ class SameAliasImportViolation(ASTStyleViolation):
     """
     This rule forbids to use the same alias as the original name in imports.
 
+    Why would you even do this in the first place?
+    However, sometimes we see this error in the real code.
+
     Example::
 
         # Correct:

wemake_python_styleguide/errors/modules.py

@@ -4,6 +4,12 @@
 These rules checks that modules are defined correctly.
 
 Please, take a note that these rules are not applied to packages.
+
+Things we check here:
+
+1. Naming
+2. Contents: some modules must have contents, some must not
+
 """
 
 from wemake_python_styleguide.errors.base import SimpleStyleViolation