Adds configuration docs, closes #302

Author: sobolevn

CHANGELOG.md

@@ -38,6 +38,7 @@ We used to have incremental versioning before `0.1.0`.
 - Improves tests: now testing almost all violations inside `noqa.py`
 - Improves tests: now testing violations text
 - Improves tests: now all common patters live in related `conftest.py`
+- Improves docs: now all configuration options are listed in the violations
 
 
 ## 0.3.0 aka The Hacktoberfest Feast

README.md

@@ -78,7 +78,10 @@ We are *not* planning to do the following things:
 
 ## Contributing
 
+We warmly welcome any contributions!
+
 See ["Contributing" section](https://wemake-python-styleguide.readthedocs.io/en/latest/_pages/contributing.html) in the documentation if you want to contribute.
+
 You can also check which [issues need some help](https://github.com/wemake-services/wemake-python-styleguide/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) right now.
 
 

docs/conf.py

@@ -69,7 +69,7 @@ def _get_project_meta():
     'added_value',
 ]
 
-autoclass_content = 'both'
+autoclass_content = 'class'
 autodoc_member_order = 'bysource'
 
 autodoc_mock_imports = [

tests/test_violations/test_docs.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+from wemake_python_styleguide.options.config import Configuration
+
 
 def test_all_violations_are_documented(all_module_violations):
     """Ensures that all violations are documented."""
@@ -38,3 +40,21 @@ def test_violation_error_text(all_violations):
             assert violation.error_template.endswith(error_format)
         else:
             assert '{0}' not in violation.error_template
+
+
+def test_configuration(all_violations):
+    """Ensures that all configuration options are listed in the docs."""
+    option_listed = dict.fromkeys([
+        option.long_option_name for option in Configuration.options
+    ], False)
+
+    for violation in all_violations:
+        for option in option_listed.keys():
+            if option in violation.__doc__:
+                option_listed[option] = True
+
+                assert 'Configuration:' in violation.__doc__
+                assert 'Default:' in violation.__doc__
+
+    for option, is_listed in option_listed.items():
+        assert is_listed, option

wemake_python_styleguide/violations/best_practices.py

@@ -261,6 +261,15 @@ class InitModuleHasLogicViolation(ASTViolation):
     1. comments, since they are dropped before AST comes in play
     2. docs string, because sometimes it is required to state something
 
+    It is also fine when you have different users that use your code.
+    And you do not want to break everything for them.
+    In this case this rule can be configured.
+
+    Configuration:
+        This rule is configurable with ``--i-control-code``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.I_CONTROL_CODE`
+
     .. versionadded:: 0.1.0
 
     Note:

wemake_python_styleguide/violations/complexity.py

@@ -92,13 +92,16 @@ class JonesScoreViolation(SimpleViolation):
     Solution:
         Refactor the module contents.
 
-    See also:
-        https://github.com/Miserlou/JonesComplexity
-
-    This rule is configurable with ``--max-module-score``.
+    Configuration:
+        This rule is configurable with ``--max-jones-score``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_JONES_SCORE`
 
     .. versionadded:: 0.1.0
 
+    See also:
+        https://github.com/Miserlou/JonesComplexity
+
     Note:
         Returns Z200 as error code
 
@@ -136,7 +139,9 @@ class TooManyImportsViolation(SimpleViolation):
     We do not make any differences between
     ``import`` and ``from ... import ...``.
 
-    This rule is configurable with ``--max-imports``.
+    Configuration:
+        This rule is configurable with ``--max-imports``.
+        Default: :str:`wemake_python_styleguide.options.defaults.MAX_IMPORTS`
 
     .. versionadded:: 0.1.0
 
@@ -167,7 +172,10 @@ class TooManyModuleMembersViolation(SimpleViolation):
     We also do not care about functions and classes being public or not.
     However, methods are counted separately on a per-class basis.
 
-    This rule is configurable with ``--max-module-members``.
+    Configuration:
+        This rule is configurable with ``--max-module-members``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_MODULE_MEMBERS`
 
     .. versionadded:: 0.1.0
 
@@ -221,7 +229,10 @@ def second_function(argument):
     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.
 
-    This rule is configurable with ``--max-local-variables``.
+    Configuration:
+        This rule is configurable with ``--max-local-variables``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_LOCAL_VARIABLES`
 
     .. versionadded:: 0.1.0
 
@@ -249,7 +260,9 @@ class TooManyArgumentsViolation(ASTViolation):
         Split function into several functions.
         Then it will be easier to use them.
 
-    This rule is configurable with ``--max-arguments``.
+    Configuration:
+        This rule is configurable with ``--max-arguments``.
+        Default: :str:`wemake_python_styleguide.options.defaults.MAX_ARGUMENTS`
 
     .. versionadded:: 0.1.0
 
@@ -276,7 +289,9 @@ class TooManyReturnsViolation(ASTViolation):
     Solution:
         Change your design.
 
-    This rule is configurable with ``--max-returns``.
+    Configuration:
+        This rule is configurable with ``--max-returns``.
+        Default: :str:`wemake_python_styleguide.options.defaults.MAX_RETURNS`
 
     .. versionadded:: 0.1.0
 
@@ -302,7 +317,10 @@ class TooManyExpressionsViolation(ASTViolation):
     Solution:
         Split function into several functions, refactor your API.
 
-    This rule is configurable with ``--max-expressions``.
+    Configuration:
+        This rule is configurable with ``--max-expressions``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_EXPRESSIONS`
 
     .. versionadded:: 0.1.0
 
@@ -331,17 +349,21 @@ class TooManyMethodsViolation(ASTViolation):
         Split this class into several classes.
         Then use composition or inheritance to refactor your code.
         This will protect you from "God object" anti-pattern.
-        See: https://en.wikipedia.org/wiki/God_object
 
     We do not make any difference between instance and class methods.
     We also do not care about functions and classes being public or not.
     We also do not count inherited methods from parents.
     This rule does not count attributes of a class.
 
-    This rule is configurable with ``--max-methods``.
+    Configuration:
+        This rule is configurable with ``--max-methods``.
+        Default: :str:`wemake_python_styleguide.options.defaults.MAX_METHODS`
 
     .. versionadded:: 0.1.0
 
+    See also:
+        https://en.wikipedia.org/wiki/God_object
+
     Note:
         Returns Z214 as error code
 
@@ -368,7 +390,10 @@ class TooDeepNestingViolation(ASTViolation):
         We need to refactor our complex construction into simpler ones.
         We can use new functions or different constructions.
 
-    This rule is configurable with ``--max-offset-blocks``.
+    Configuration:
+        This rule is configurable with ``--max-offset-blocks``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_OFFSET_BLOCKS`
 
     .. versionadded:: 0.1.0
 
@@ -411,13 +436,16 @@ class LineComplexityViolation(ASTViolation):
         With this technique a single new node in a line might trigger a complex
         refactoring process including several modules.
 
-    See also:
-        https://github.com/Miserlou/JonesComplexity
-
-    This rule is configurable with ``--max-line-complexity``.
+    Configuration:
+        This rule is configurable with ``--max-line-complexity``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_LINE_COMPLEXITY`
 
     .. versionadded:: 0.1.0
 
+    See also:
+        https://github.com/Miserlou/JonesComplexity
+
     Note:
         Returns Z221 as error code
 
@@ -453,7 +481,10 @@ class TooManyConditionsViolation(ASTViolation):
         # The next line has 2 conditions:
         if x_coord > 1 and x_coord < 10: ...
 
-    This rule is configurable with ``--max-conditions``.
+    Configuration:
+        This rule is configurable with ``--max-conditions``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_CONDITIONS`
 
     .. versionadded:: 0.1.0
 
@@ -482,7 +513,9 @@ class TooManyElifsViolation(ASTViolation):
         For example, you can use some interface that
         just call a specific method without ``if``.
 
-    This rule is configurable with ``--max-elifs``.
+    Configuration:
+        This rule is configurable with ``--max-elifs``.
+        Default: :str:`wemake_python_styleguide.options.defaults.MAX_ELIFS`
 
     .. versionadded:: 0.1.0
 
@@ -547,8 +580,6 @@ class TooManyBaseClassesViolation(ASTViolation):
     Solution:
         Restrict the number of base classes.
 
-    This rule is configurable with ``--max-base-classes``.
-
     Example::
 
        # Correct:
@@ -563,6 +594,11 @@ class SomeClassName(
            AddedClass,
         ): ...
 
+    Configuration:
+        This rule is configurable with ``--max-base-classes``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_BASE_CLASSES`
+
     .. versionadded:: 0.3.0
 
     Note:

wemake_python_styleguide/violations/naming.py

@@ -316,7 +316,6 @@ class TooShortNameViolation(MaybeASTViolation):
 
     This rule checks: modules, variables, attributes,
     functions, methods, and classes.
-    This rule is configurable with ``--min-name-length``.
 
     Example::
 
@@ -328,6 +327,11 @@ class TooShortNameViolation(MaybeASTViolation):
         x = 1
         y = 2
 
+    Configuration:
+        This rule is configurable with ``--min-name-length``.
+        Default:
+        :str:`wemake_python_styleguide.options.defaults.MAX_NAME_LENGTH`
+
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.4.0