Merge branch 'develop' of https://github.com/timothycrosley/isort into issue/1443/initial-progressissue/1443/initial-progress

3 files changed, 78 insertions, 16 deletions

diff --git a/docs/configuration/config_files.md b/docs/configuration/config_files.md
index a3d983c2..7cda9cd3 100644
--- a/docs/configuration/config_files.md
+++ b/docs/configuration/config_files.md
@@ -1,11 +1,13 @@
 Supported Config Files
 ========
 
-isort supports a variety of standard config formats, to allow customizations to easily be integrated into any project.
+isort supports various standard config formats to allow customizations to be integrated into any project quickly.
 When applying configurations, isort looks for the closest supported config file, in the order files are listed below.
-You can manually specify the settings file or path by setting `--settings-path` from the commandline, otherwise isort will
+You can manually specify the settings file or path by setting `--settings-path` from the command-line. Otherwise, isort will
 traverse up to 25 parent directories until it finds a suitable config file.
-As soon as it finds a file, it stops looking. isort **never** merges config files together due to the confusion it can cause.
+As soon as it finds a file, it stops looking. The config file search is done relative to the current directory if `isort .`
+or a file stream is passed in, or relative to the first path passed in if multiple paths are passed in.
+isort **never** merges config files together due to the confusion it can cause.
 
 !!! tip
     You can always introspect the configuration settings isort determined, and find out which config file it picked up, by running `isort . --show-config`
@@ -75,3 +77,12 @@ indent_size = 4
 skip = build,.tox,venv
 src_paths=isort,test
 ```
+
+## Custom config files
+
+Optionally, you can also create a config file with a custom name, or directly point isort to a config file that falls lower in the priority order, by using [--settings-file](https://pycqa.github.io/isort/docs/configuration/options/#settings-path).
+This can be useful, for instance, if you want to have one configuration for `.py` files and another for `.pyx` - while keeping the config files at the root of your repository.
+
+!!! tip
+    Custom config files should place their configuration options inside an `[isort]` section and never a generic `[settings]` section. This is because isort can't know for sure
+    how other tools are utilizing the config file.
diff --git a/docs/configuration/options.md b/docs/configuration/options.md
index 10c1cfb8..bf220524 100644
--- a/docs/configuration/options.md
+++ b/docs/configuration/options.md
@@ -4,7 +4,8 @@ As a code formatter isort has opinions. However, it also allows you to have your
 isort will disagree but commit to your way of formatting. To enable this, isort exposes a plethora of options to specify
 how you want your imports sorted, organized, and formatted.
 
-Too busy to build your perfect isort configuration? For curated common configurations, see isort's [built-in profiles](https://pycqa.github.io/isort/docs/configuration/profiles/).
+Too busy to build your perfect isort configuration? For curated common configurations, see isort's [built-in
+profiles](https://pycqa.github.io/isort/docs/configuration/profiles/).
 
 ## Python Version
 
@@ -35,7 +36,7 @@ Force specific imports to the top of their appropriate section.
 Files that sort imports should skip over. If you want to skip multiple files you should specify twice: --skip file1 --skip file2.
 
 **Type:** Frozenset  
-**Default:** `('.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.tox', '.venv', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv')`  
+**Default:** `('.bzr', '.direnv', '.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.svn', '.tox', '.venv', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv')`  
 **Python & Config File Name:** skip  
 **CLI Flags:**
 
@@ -128,7 +129,7 @@ Put all imports into the same section bucket
 
 ## Known Future Library
 
-Force isort to recognize a module as part of the future compatibility libraries.
+Force isort to recognize a module as part of Python's internal future compatibility libraries. WARNING: this overrides the behavior of __future__ handling and therefore can result in code that can't execute. If you're looking to add dependencies such as six a better option is to create a another section below --future using custom sections. See: https://github.com/PyCQA/isort#custom-sections-and-ordering and the discussion here: https://github.com/PyCQA/isort/issues/1463.
 
 **Type:** Frozenset  
 **Default:** `('__future__',)`  
@@ -293,14 +294,13 @@ Sort imports by their string length.
 - --ls
 - --length-sort
 
-## Length Sort Straight Imports
+## Length Sort Straight
 
-Sort straight imports by their string length. Similar to `length_sort` but applies only to
-straight imports and doesn't affect from imports.
+Sort straight imports by their string length.
 
-**Type:** Bool
-**Default:** `False`
-**Python & Config File Name:** length_sort_straight
+**Type:** Bool  
+**Default:** `False`  
+**Python & Config File Name:** length_sort_straight  
 **CLI Flags:**
 
 - --lss
@@ -602,7 +602,7 @@ Force all imports to be sorted as a single section
 
 ## Force Grid Wrap
 
-Force number of from imports (defaults to 2) to be grid wrapped regardless of line length
+Force number of from imports (defaults to 2 when passed as CLI flag without value) to be grid wrapped regardless of line length. If 0 is passed in (the global default) only line length is considered.
 
 **Type:** Int  
 **Default:** `0`  
@@ -880,7 +880,7 @@ Tells isort to treat all single line comments as if they are code.
 Specifies what extensions isort can be ran against.
 
 **Type:** Frozenset  
-**Default:** `('.py', '.pyi', '.pyx')`  
+**Default:** `('py', 'pyi', 'pyx')`  
 **Python & Config File Name:** supported_extensions  
 **CLI Flags:**
 
@@ -893,12 +893,62 @@ Specifies what extensions isort can be ran against.
 Specifies what extensions isort can never be ran against.
 
 **Type:** Frozenset  
-**Default:** `('.pex',)`  
+**Default:** `('pex',)`  
 **Python & Config File Name:** blocked_extensions  
 **CLI Flags:**
 
 - --blocked-extension
 
+## Constants
+
+**No Description**
+
+**Type:** Frozenset  
+**Default:** `frozenset()`  
+**Python & Config File Name:** constants  
+**CLI Flags:** **Not Supported**
+
+## Classes
+
+**No Description**
+
+**Type:** Frozenset  
+**Default:** `frozenset()`  
+**Python & Config File Name:** classes  
+**CLI Flags:** **Not Supported**
+
+## Variables
+
+**No Description**
+
+**Type:** Frozenset  
+**Default:** `frozenset()`  
+**Python & Config File Name:** variables  
+**CLI Flags:** **Not Supported**
+
+## Dedup Headings
+
+Tells isort to only show an identical custom import heading comment once, even if there are multiple sections with the comment set.
+
+**Type:** Bool  
+**Default:** `False`  
+**Python & Config File Name:** dedup_headings  
+**CLI Flags:**
+
+- --dedup-headings
+
+## Only Sections
+
+Causes imports to be sorted only based on their sections like STDLIB,THIRDPARTY etc. Imports are unaltered and keep their relative positions within the different sections.
+
+**Type:** Bool  
+**Default:** `False`  
+**Python & Config File Name:** only_sections  
+**CLI Flags:**
+
+- --only-sections
+- --os
+
 ## Check
 
 Checks the file for unsorted / unformatted imports and prints them to the command line without modifying the file.
@@ -948,7 +998,7 @@ Number of files to process in parallel.
 - -j
 - --jobs
 
-## Don't Order By Type
+## Dont Order By Type
 
 Don't order imports by type, which is determined by case, in addition to alphabetically.
 
diff --git a/docs/configuration/profiles.md b/docs/configuration/profiles.md
index 3b0e4cc4..1b6d6f75 100644
--- a/docs/configuration/profiles.md
+++ b/docs/configuration/profiles.md
@@ -30,6 +30,7 @@ To use any of the listed profiles, use `isort --profile PROFILE_NAME` from the c
 
  - **multi_line_output**: `3`
  - **force_grid_wrap**: `2`
+ - **lines_after_imports**: `2`
 
 #google