Split documentation to multiple files in docs/ and use markdown

docs/incompatibilities.md

@@ -0,0 +1,14 @@
+# Backward incompatible migrations
+
+The linter analyses your migrations and checks the SQL for:
+
+- Added `NOT NULL` columns, which don't have a DEFAULT value
+- Dropping columns
+- Dropping tables
+- Renaming columns
+- Renaming tables
+- Altering columns (which can be backward compatible and potentially ignored)
+- Adding a unique constraint
+
+Those are the most important and frequent backward incompatible migrations.
+We are happy to add more if you can specify them to us.

docs/internals/cache.md

@@ -0,0 +1,10 @@
+# Cache
+
+By default, the linter uses a cache to prevent linting the same migration multiple times.
+The default location of the cache on Linux is
+`/home/<username>/.cache/django-migration-linter/<version>/<ldjango-project>_<database_name>.pickle`.
+
+Since the linter uses hashes of the file's content, modifying a migration file will re-run the linter on that migration.
+If you want to run the linter without cache, use the flag `--no-cache`.
+If you want to invalidate the cache, delete the cache folder.
+The cache folder can also be defined manually through the `--cache-path` option.

docs/internals/publishing.md

@@ -0,0 +1,7 @@
+# Publishing the package
+
+A small note on how the linter is usually published to PyPi:
+
+- `python3 setup.py sdist bdist_wheel --universal`
+- `twine upload dist/django_migration_linter-X.Y.Z-py2.py3-none-any.whl dist/django-migration-linter-X.Y.Z.tar.gz`
+

docs/internals/testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+The easiest way to run the tests is to invoke `tox` on the command line.
+
+You will need to install the test requirements, which can be found in the ``setup.py`` file.
+A good way to get started is to install the development version of the linter by doing ``pip install -e .[test]``.
+
+To be able to fully test the linter, you will need both MySQL and PostgreSQL databases running.
+You can either tweak the ``tests/test_project/settings.py`` file to get your DB settings right, or to have databases and users corresponding to the default Travis users.

docs/usage.md

@@ -0,0 +1,41 @@
+# Usage
+
+## Command line usage
+
+The linter is installed as a Django app and is integrated through the Django management command system. 
+
+`python manage.py lintmigrations [GIT_COMMIT_ID] ...`
+
+Detailed command line options:
+
+|                   Parameter                                  |                                        Description                                                                          |
+|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+|`GIT_COMMIT_ID`                                               | If specified, only migrations since this commit will be taken into account. If not specified, all migrations will be linted.|
+|`--ignore-name-contains IGNORE_NAME_CONTAINS`                 | Ignore migrations containing this name.                                                                                     |
+|`--ignore-name IGNORE_NAME [IGNORE_NAME ...]`                 | Ignore migrations with exactly one of these names.                                                                          |
+|`--include-apps INCLUDE_APPS [INCLUDE_APPS ...]`              | Check only migrations that are in the specified django apps.                                                                |
+|`--exclude-apps EXCLUDE_APPS [EXCLUDE_APPS ...]`              | Ignore migrations that are in the specified django apps.                                                                    |
+|`--exclude-migration-tests MIGRATION_TEST_CODE [...]`         | Specify backward incompatible migration tests to be ignored using the code (e.g. ALTER_COLUMN).                             |
+|`--verbosity or -v {0,1,2,3}`                                 | Print more information during execution.                                                                                    |
+|`--database DATABASE`                                         | Specify the database for which to generate the SQL. Defaults to *default*.                                                  |
+|`--cache-path PATH`                                           | specify a directory that should be used to store cache-files in.                                                            |
+|`--no-cache`                                                  | Don't use a cache.                                                                                                          |
+|`--applied-migrations`                                        | Only lint migrations that are applied to the selected database. Other migrations are ignored.                               |
+|`--unapplied-migrations`                                      | Only lint migrations that are not yet applied to the selected database. Other migrations are ignored.                       |
+|`--project-root-path DJANGO_PROJECT_FOLDER`                   | An absolute or relative path to the django project.                                                                         |
+|`--include-migrations-from FILE_PATH`                         | If specified, only migrations listed in the given file will be considered.                                                  |
+|`--quiet or -q {ok,ignore,error}`                             | Suppress certain output messages, instead of writing them to stdout.                                                        |
+
+## Ignoring migration tests
+
+You can also ignore backward incompatible migration tests by adding this option during execution:
+
+`python manage.py lintmigrations --exclude-migration-tests ALTER_COLUMN`
+
+The migration test codes can be found in the [corresponding source code files](../django_migration_linter/sql_analyser/base.py).
+
+## Production usage example
+
+[3YOURMIND](https://www.3yourmind.com/) is running the linter on every build getting pushed through CI.
+That enables to be sure that the migrations will allow A/B testing, Blue/Green deployment and they won't break your development environment.
+A non-zero error code is returned to express that at least one invalid migration has been found.