Skip to content

Commit

Permalink
docs: transfer README.md content to Sphinx
Browse files Browse the repository at this point in the history
  • Loading branch information
@andreoliwa
andreoliwa committed Aug 15, 2019
1 parent 75e7f69 commit 0151931
Show file tree
Hide file tree
Showing 10 changed files with 321 additions and 120 deletions.
4 changes: 2 additions & 2 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ poetry:
# ERROR: File "setup.py" not found. Directory cannot be installed in editable mode: ~/Code/nitpick
# (A "pyproject.toml" file was found, but editable mode currently requires a setup.py based build.)
# TODO remove this if ever pip changes this behaviour
xpoetry setup-py
poetryx setup-py
touch .cache/make/auto-poetry
-rm .cache/make/run

Expand All @@ -56,7 +56,7 @@ sphinx:
# $(O) is meant as a shortcut for $(SPHINXOPTS).
.cache/make/sphinx: docs *.rst *.md
-rm -rf docs/source
sphinx-apidoc --force --module-first --separate --implicit-namespaces --output-dir docs/source src/
sphinx-apidoc --force --module-first --separate --implicit-namespaces --output-dir docs/source src/nitpick/
@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
touch .cache/make/sphinx

Expand Down
163 changes: 51 additions & 112 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,14 @@
# nitpick
# Nitpick

[default style file]: (https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml)
[TOML]: (https://github.com/toml-lang/toml)
[flake8]: (https://gitlab.com/pycqa/flake8)
[isort]: (https://github.com/timothycrosley/isort)
[black]: (https://github.com/psf/black)
[mypy]: (http://mypy-lang.org/)
[pylint]: (https://www.pylint.org)
[pre-commit]: (https://pre-commit.com/)
[poetry]: (https://github.com/sdispater/poetry/)

[![PyPI](https://img.shields.io/pypi/v/nitpick.svg)](https://pypi.python.org/pypi/nitpick)
[![Travis CI](https://travis-ci.com/andreoliwa/nitpick.svg)](https://travis-ci.com/andreoliwa/nitpick)
Expand All @@ -8,138 +18,67 @@
[![Test Coverage](https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/test_coverage)](https://codeclimate.com/github/andreoliwa/nitpick/test_coverage)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/nitpick.svg)](https://pypi.org/project/nitpick/)
[![Project License](https://img.shields.io/pypi/l/nitpick.svg)](https://pypi.org/project/nitpick/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=andreoliwa/nitpick)](https://dependabot.com)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

Flake8 plugin to enforce the same lint configuration (flake8, isort, mypy, pylint) across multiple Python projects.
Flake8 plugin to enforce the same tool configuration ([flake8], [isort], [mypy], [pylint]...) across multiple Python projects.

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.:

- `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.

---

- [Installation and usage](#installation-and-usage)
- [Style file](#style-file)
- [setup.cfg](#setupcfg)

---

## Installation and usage

To try the package, simply install it (in a virtualenv or globally, wherever) and run `flake8`:

$ pip install -U nitpick
$ flake8

You will see warnings if your project configuration is different than [the default style file](https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml).

### As a pre-commit hook

If you use [pre-commit](https://pre-commit.com/) on your project, add this to the `.pre-commit-config.yaml` in your repository:

repos:
- repo: https://github.com/andreoliwa/nitpick
rev: v0.20.0
hooks:
# Run nitpick and several other flake8 plugins
- id: nitpick-all
# Check only nitpick errors, ignore other flake8 plugins
- id: nitpick-only

Use one hook or the other (`nitpick-all` **or** `nitpick-only`), not both.
To check all the other flake8 plugins that are installed with `nitpick`, see the [pyproject.toml](pyproject.toml).
Useful if you maintain multiple projects and want to use the same configs in all of them.

## Style file

### Configure your own style file

Change your project config on `pyproject.toml`, and configure your own style like this:

[tool.nitpick]
style = "https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/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).
A "nitpick code style" is a [TOML] file with the settings that should be present in config files from other tools.

You can also use multiple styles and mix local files and URLs:
Example of a style:

[tool.nitpick]
style = ["/path/to/first.toml", "/another/path/to/second.toml", "https://example.com/on/the/web/third.toml"]
```
["pyproject.toml".tool.black]
line-length = 120
The order is important: each style will override any keys that might be set by the previous .toml file.
If a key is defined in more than one file, the value from the last file will prevail.
["pyproject.toml".tool.poetry.dev-dependencies]
pylint = "*"
### Default search order for a style file
["setup.cfg".flake8]
ignore = "D107,D202,D203,D401"
max-line-length = 120
inline-quotes = "double"
1. A file or URL configured in the `pyproject.toml` file, `[tool.nitpick]` section, `style` key, as [described above](#configure-your-own-style-file).
["setup.cfg".isort]
line_length = 120
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
combine_as_imports = true
```

2. Any `nitpick-style.toml` file found in the current directory (the one in which `flake8` runs from) or above.
This style will assert that:

3. If no style is found, then [the default style file from GitHub](https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml) is used.
- ... [black], [isort] and [flake8] have a line length of 120;
- ... [flake8] and [isort] are configured as above in `setup.cfg`;
- ... [pylint] is present as a project dev dependency (in `pyproject.toml`, used by [poetry]).

### Style file syntax
## Quick setup

NOTE: The project is still experimental; the style file syntax might slightly change before the 1.0 stable release.
The `NIP*` error codes also might change.

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/python/black#configuration-format) with a line length of 120, you use this in your `pyproject.toml`:

[tool.black]
line-length = 120

To enforce that all your projects use this same line length, add this to your `nitpick-style.toml` file:

["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:

[mypy]
ignore_missing_imports = true

To enforce all your projects to ignore missing imports, add this to your `nitpick-style.toml` file:

["setup.cfg".mypy]
ignore_missing_imports = true

### Present files

To enforce that certain files should exist in the project, you can add them to the style file as a dictionary of "file name" and "extra message".
Use an empty string to not display any extra message.

[nitpick.files.present]
".editorconfig" = ""
"CHANGELOG.md" = "A project should have a changelog"

### Absent files
To try the package, simply install it (in a virtualenv or globally, wherever) and run `flake8`:

To enforce that certain files should not exist in the project, you can add them to the style file.
$ pip install -U nitpick
$ flake8

[nitpick.files.absent]
"some_file.txt" = "This is an optional extra string to display after the warning"
"another_file.env" = ""
`nitpick` will use the opinionated [default style file].

Multiple files can be configured as above.
The message is optional.
You can use it as a template to create your own style.

## setup.cfg
### Run as a pre-commit hook (recommended)

### Comma separated values
If you use [pre-commit] on your project (you should), add this to the `.pre-commit-config.yaml` in your repository:

On `setup.cfg`, some keys are lists of multiple values separated by commas, like `flake8.ignore`.
repos:
- repo: https://github.com/andreoliwa/nitpick
rev: v0.20.0
hooks:
- id: nitpick

On the style file, it's possible to indicate which key/value pairs should be treated as multiple values instead of an exact string.
Multiple keys can be added.
---

[nitpick.files."setup.cfg"]
comma_separated_values = ["flake8.ignore", "isort.some_key", "another_section.another_key"]
For more details on styles and which configuration files are currently supported, [see the full documentation](https://nitpick.readthedocs.io/).
31 changes: 31 additions & 0 deletions docs/config.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
.. _config:

Config
======

Files that should exist
-----------------------

To enforce that certain files should exist in the project, you can add them to the style file as a dictionary of "file name" and "extra message".

Use an empty string to not display any extra message.

.. code-block::
[nitpick.files.present]
".editorconfig" = ""
"CHANGELOG.md" = "A project should have a changelog"
Files that should be deleted
----------------------------

To enforce that certain files should not exist in the project, you can add them to the style file.

.. code-block::
[nitpick.files.absent]
"some_file.txt" = "This is an optional extra string to display after the warning"
"another_file.env" = ""
Multiple files can be configured as above.
The message is optional.
124 changes: 121 additions & 3 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,128 @@
Welcome to nitpick's documentation!
===================================
Nitpick
=======

.. _default style file: https://raw.githubusercontent.com/andreoliwa/nitpick/v0.20.0/nitpick-style.toml
.. _TOML: https://github.com/toml-lang/toml
.. _flake8: https://gitlab.com/pycqa/flake8
.. _isort: https://github.com/timothycrosley/isort
.. _black: https://github.com/psf/black
.. _mypy: http://mypy-lang.org/
.. _pylint: https://www.pylint.org
.. _pre-commit: https://pre-commit.com/
.. _poetry: https://github.com/sdispater/poetry/

.. image:: https://img.shields.io/pypi/v/nitpick.svg
:target: https://pypi.python.org/pypi/nitpick
:alt: PyPI
.. image:: https://travis-ci.com/andreoliwa/nitpick.svg
:target: https://travis-ci.com/andreoliwa/nitpick
:alt: Travis CI
.. image:: https://readthedocs.org/projects/nitpick/badge/?version=latest
:target: https://nitpick.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://coveralls.io/repos/github/andreoliwa/nitpick/badge.svg
:target: https://coveralls.io/github/andreoliwa/nitpick
:alt: Coveralls
.. image:: https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/maintainability
:target: https://codeclimate.com/github/andreoliwa/nitpick/maintainability
:alt: Maintainability
.. image:: https://api.codeclimate.com/v1/badges/61e0cdc48e24e76a0460/test_coverage
:target: https://codeclimate.com/github/andreoliwa/nitpick/test_coverage
:alt: Test Coverage
.. image:: https://img.shields.io/pypi/pyversions/nitpick.svg
:target: https://pypi.org/project/nitpick/
:alt: Supported Python versions
.. image:: https://img.shields.io/pypi/l/nitpick.svg
:target: https://pypi.org/project/nitpick/
:alt: Project License
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code style: black
.. image:: https://api.dependabot.com/badges/status?host=github&repo=andreoliwa/nitpick
:target: https://dependabot.com
:alt: Dependabot Status
.. image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
:target: https://github.com/semantic-release/semantic-release
:alt: semantic-release

Flake8 plugin to enforce the same tool configuration (flake8_, isort_, mypy_, pylint_...) across multiple Python projects.

Useful if you maintain multiple projects and want to use the same configs in all of them.

.. warning::

This project is still experimental and the API is not fully defined:

- The style file syntax might slightly change before the 1.0 stable release.
- The numbers in the ``NIP*`` error codes might change.

Style file
----------

A "nitpick code style" is a TOML_ file with the settings that should be present in config files from other tools.

Example of a style:

.. code-block::
["pyproject.toml".tool.black]
line-length = 120
["pyproject.toml".tool.poetry.dev-dependencies]
pylint = "*"
["setup.cfg".flake8]
ignore = "D107,D202,D203,D401"
max-line-length = 120
inline-quotes = "double"
["setup.cfg".isort]
line_length = 120
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
combine_as_imports = true
This style will assert that:

- ... black_, isort_ and flake8_ have a line length of 120;
- ... flake8_ and isort_ are configured as above in ``setup.cfg``;
- ... pylint_ is present as a project dev dependency (in ``pyproject.toml``, used by poetry_).

Quick setup
-----------

To try the package, simply install it (in a virtualenv or globally, wherever) and run ``flake8``:

.. code-block::
$ pip install -U nitpick
$ flake8
``nitpick`` will use the opinionated `default style file`_.

You can use it as a template to create your own style.

Run as a pre-commit hook (recommended)
--------------------------------------

If you use pre-commit_ on your project (you should), add this to the ``.pre-commit-config.yaml`` in your repository:

.. code-block::
repos:
- repo: https://github.com/andreoliwa/nitpick
rev: v0.20.0
hooks:
- id: nitpick
.. toctree::
:maxdepth: 2
:caption: Contents:

self
styles
config
supported_files
contributing
authors

Expand Down

0 comments on commit 0151931

Please sign in to comment.