docs: Add docs on how to configure pyproject.toml and style

README.rst

@@ -9,21 +9,81 @@ flake8-nitpick
      :target: https://pyup.io/repos/github/andreoliwa/flake8-nitpick/
      :alt: Updates
 
-A code style guide for Python projects.
+Flake8 plugin to reuse the same lint configuration across multiple Python projects.
 
-A central place to keep all linting and doc generation tools, so you don't need to install these dependencies in every project you create.
+A "nitpick code style" is a `TOML <https://github.com/toml-lang/toml>`_ file with settings that should be present in config files from other tools. E.g.:
 
-Setup
------
+- ``pyproject.toml`` and ``setup.cfg`` (used by `flake8 <http://flake8.pycqa.org/>`_, `black <https://black.readthedocs.io/>`_, `isort <https://isort.readthedocs.io/>`_, `mypy <https://mypy.readthedocs.io/>`_);
+- ``.pylintrc`` (used by `pylint <https://pylint.readthedocs.io/>`_ config);
+- more files to come.
 
-To install flake8-nitpick, run:
+Quick setup
+-----------
+
+Simply install the package (in a virtualenv or globally, wherever) and run ``flake8``:
 
 .. code-block:: console
 
-    $ pip install flake8-nitpick
+    $ pip install -U flake8-nitpick
+    $ flake8
+
+You will see warnings if your project configuration is different than `the default style file <https://raw.githubusercontent.com/andreoliwa/flake8-nitpick/master/nitpick-style.toml>`_.
+
+Configure your own style file
+-----------------------------
+
+Change your project config on ``pyproject.toml``, and configure your own style like this:
+
+.. code-block:: ini
+
+    [tool.nitpick]
+    style = "https://raw.githubusercontent.com/andreoliwa/flake8-nitpick/master/nitpick-style.toml"
+
+You can set ``style`` with any local file or URL. E.g.: you can use the raw URL of a `GitHub Gist <https://gist.github.com>`_.
+
+Default search order for a style file
+-------------------------------------
+
+1. A file or URL configured in the ``pyproject.toml`` file, ``[tool.nitpick]`` section, ``style`` key, as `described above <Configure your own style file>`_.
+
+2. Any ``nitpick-style.toml`` file found in the current directory (the one in which ``flake8`` runs from) or above.
+
+3. If no style is found, then `the default style file from GitHub <https://raw.githubusercontent.com/andreoliwa/flake8-nitpick/master/nitpick-style.toml>`_ is used.
+
+Style file syntax
+-----------------
+
+A style file contains basically the configuration options you want to enforce in all your projects.
+
+They are just the config to the tool, prefixed with the name of the config file.
+
+E.g.: To `configure the black formatter <https://github.com/ambv/black#configuration-format>`_ with a line length of 120, you use this in your ``pyproject.toml``:
+
+.. code-block:: ini
+
+    [tool.black]
+    line-length = 120
+
+To enforce that all your projects use this same line length, add this to your ``nitpick-style.toml`` file:
+
+.. code-block:: ini
+
+    ["pyproject.toml".tool.black]
+    line-length = 120
+
+It's the same exact section/key, just prefixed with the config file name (``"pyproject.toml".``)
+
+The same works for ``setup.cfg``.
+To `configure mypy <https://mypy.readthedocs.io/en/latest/config_file.html#config-file-format>`_ to ignore missing imports in your project:
+
+.. code-block:: ini
+
+    [mypy]
+    ignore_missing_imports = true
+
+To enforce all your projects to ignore missing imports, add this to your ``nitpick-style.toml`` file:
 
-To nitpick your project:
+.. code-block:: ini
 
-- Add ``flake8-nitpick`` to your ``Pipfile`` or ``requirements.txt``;
-- Configure your ``setup.cfg`` file;
-- Tools like ``flake8`` and `isort`` will be available on the CLI.
+    ["setup.cfg".mypy]
+    ignore_missing_imports = true

flake8_nitpick/__init__.py

@@ -100,7 +100,7 @@ def find_style(self) -> Optional[Path]:
             LOG.info("Loading cached style: %s", style_path)
             return style_path
 
-        style: str = self.pyproject_toml.get("style", "")
+        style: str = self.tool_nitpick_toml.get("style", "")
         if style.startswith("http"):
             # If the style is a URL, save the contents in the cache dir
             style_path = self.load_style_from_url(style)

setup.py

@@ -14,7 +14,7 @@
 
 # Package meta-data.
 NAME = "flake8_nitpick"
-DESCRIPTION = "Flake8 plugin to share the same code style for multiple Python projects"
+DESCRIPTION = "Flake8 plugin to reuse the same lint configuration across multiple Python projects"
 URL = "https://github.com/andreoliwa/flake8-nitpick"
 EMAIL = "[email protected]"
 AUTHOR = "W. Augusto Andreoli"
@@ -105,12 +105,17 @@ def run(self):
     classifiers=[
         # Trove classifiers
         # Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
+        "Development Status :: 3 - Alpha",
+        "Environment :: Plugins",
+        "Intended Audience :: Developers",
         "License :: OSI Approved :: MIT License",
+        "Operating System :: MacOS",
+        "Operating System :: Unix",
         "Programming Language :: Python",
+        "Programming Language :: Python :: 3 :: Only",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: Implementation :: CPython",
-        "Programming Language :: Python :: Implementation :: PyPy",
+        "Topic :: Software Development :: Quality Assurance",
     ],
     # $ setup.py publish support.
     cmdclass={"upload": UploadCommand},