Switch to portray compatible doc setup / MD usage exclusively

7 files changed, 893 insertions, 676 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..24da9bae
--- /dev/null
+++ b/README.md
@@ -0,0 +1,698 @@
+![isort](https://raw.github.com/timothycrosley/isort/master/logo.png)
+
+------------------------------------------------------------------------
+
+[![PyPI version](https://badge.fury.io/py/isort.svg)](https://badge.fury.io/py/isort)
+[![Build Status](https://travis-ci.org/timothycrosley/isort.svg?branch=master)](https://travis-ci.org/timothycrosley/isort)
+[![Code coverage Status](https://codecov.io/gh/timothycrosley/isort/branch/develop/graph/badge.svg)](https://codecov.io/gh/timothycrosley/isort)
+[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://pypi.org/project/hug/)
+[![Join the chat at https://gitter.im/timothycrosley/isort](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/timothycrosley/isort?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Downloads](https://pepy.tech/badge/isort)](https://pepy.tech/project/isort)
+
+isort your python imports for you so you don't have to.
+
+isort is a Python utility / library to sort imports alphabetically, and
+automatically separated into sections. It provides a command line
+utility, Python library and [plugins for various
+editors](https://github.com/timothycrosley/isort/wiki/isort-Plugins) to
+quickly sort all your imports. It requires Python 3.5+ to run but
+supports formatting Python 2 code too.
+
+------------------------------------------------------------------------
+
+[Get professionally supported isort with the Tidelift
+Subscription](https://tidelift.com/subscription/pkg/pypi-isort?utm_source=pypi-isort&utm_medium=referral&utm_campaign=readme)
+
+Professional support for isort is available as part of the [Tidelift
+Subscription](https://tidelift.com/subscription/pkg/pypi-isort?utm_source=pypi-isort&utm_medium=referral&utm_campaign=readme).
+Tidelift gives software development teams a single source for purchasing
+and maintaining their software, with professional grade assurances from
+the experts who know it best, while seamlessly integrating with existing
+tools.
+
+------------------------------------------------------------------------
+
+![Example Usage](https://raw.github.com/timothycrosley/isort/develop/example.gif)
+
+Before isort:
+
+```python
+from my_lib import Object
+
+print("Hey")
+
+import os
+
+from my_lib import Object3
+
+from my_lib import Object2
+
+import sys
+
+from third_party import lib15, lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14
+
+import sys
+
+from __future__ import absolute_import
+
+from third_party import lib3
+
+print("yo")
+```
+
+After isort:
+
+```python
+from __future__ import absolute_import
+
+import os
+import sys
+
+from third_party import (lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8,
+                         lib9, lib10, lib11, lib12, lib13, lib14, lib15)
+
+from my_lib import Object, Object2, Object3
+
+print("Hey")
+print("yo")
+```
+
+Installing isort
+================
+
+Installing isort is as simple as:
+
+```bash
+pip install isort
+```
+
+Install isort with requirements.txt support:
+
+```bash
+pip install isort[requirements]
+```
+
+Install isort with Pipfile support:
+
+```bash
+pip install isort[pipfile]
+```
+
+Install isort with both formats support:
+
+```bash
+pip install isort[requirements,pipfile]
+```
+
+Using isort
+===========
+
+**From the command line**:
+
+```bash
+isort mypythonfile.py mypythonfile2.py
+```
+
+or recursively:
+
+```bash
+isort -rc .
+```
+
+*which is equivalent to:*
+
+```bash
+isort **/*.py
+```
+
+or to see the proposed changes without applying them:
+
+```bash
+isort mypythonfile.py --diff
+```
+
+Finally, to atomically run isort against a project, only applying
+changes if they don't introduce syntax errors do:
+
+```bash
+isort -rc --atomic .
+```
+
+(Note: this is disabled by default as it keeps isort from being able to
+run against code written using a different version of Python)
+
+**From within Python**:
+
+```bash
+from isort import SortImports
+
+SortImports("pythonfile.py")
+```
+
+or:
+
+```bash
+from isort import SortImports
+
+new_contents = SortImports(file_contents=old_contents).output
+```
+
+**From within Kate:**
+
+```bash
+ctrl+[
+```
+
+or:
+
+```bash
+menu > Python > Sort Imports
+```
+
+Installing isort's Kate plugin
+===============================
+
+For KDE 4.13+ / Pate 2.0+:
+
+```bash
+wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin.py --output-document ~/.kde/share/apps/kate/pate/isort_plugin.py
+wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin_ui.rc --output-document ~/.kde/share/apps/kate/pate/isort_plugin_ui.rc
+wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/katepart_isort.desktop --output-document ~/.kde/share/kde4/services/katepart_isort.desktop
+```
+
+For all older versions:
+
+```bash
+wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin_old.py --output-document ~/.kde/share/apps/kate/pate/isort_plugin.py
+```
+
+You will then need to restart kate and enable Python Plugins as well as
+the isort plugin itself.
+
+Installing isort's for your preferred text editor
+==================================================
+
+Several plugins have been written that enable to use isort from within a
+variety of text-editors. You can find a full list of them [on the isort
+wiki](https://github.com/timothycrosley/isort/wiki/isort-Plugins).
+Additionally, I will enthusiastically accept pull requests that include
+plugins for other text editors and add documentation for them as I am
+notified.
+
+How does isort work?
+====================
+
+isort parses specified files for global level import lines (imports
+outside of try / except blocks, functions, etc..) and puts them all at
+the top of the file grouped together by the type of import:
+
+-   Future
+-   Python Standard Library
+-   Third Party
+-   Current Python Project
+-   Explicitly Local (. before import, as in: `from . import x`)
+-   Custom Separate Sections (Defined by forced\_separate list in
+    configuration file)
+-   Custom Sections (Defined by sections list in configuration file)
+
+Inside of each section the imports are sorted alphabetically. isort
+automatically removes duplicate python imports, and wraps long from
+imports to the specified line length (defaults to 79).
+
+When will isort not work?
+=========================
+
+If you ever have the situation where you need to have a try / except
+block in the middle of top-level imports or if your import order is
+directly linked to precedence.
+
+For example: a common practice in Django settings files is importing \*
+from various settings files to form a new settings file. In this case if
+any of the imports change order you are changing the settings definition
+itself.
+
+However, you can configure isort to skip over just these files - or even
+to force certain imports to the top.
+
+Configuring isort
+=================
+
+If you find the default isort settings do not work well for your
+project, isort provides several ways to adjust the behavior.
+
+To configure isort for a single user create a `~/.isort.cfg` or
+`$XDG_CONFIG_HOME/isort.cfg` file:
+
+```ini
+[settings]
+line_length=120
+force_to_top=file1.py,file2.py
+skip=file3.py,file4.py
+known_future_library=future,pies
+known_standard_library=std,std2
+known_third_party=randomthirdparty
+known_first_party=mylib1,mylib2
+indent='    '
+multi_line_output=3
+length_sort=1
+forced_separate=django.contrib,django.utils
+default_section=FIRSTPARTY
+no_lines_before=LOCALFOLDER
+```
+
+Additionally, you can specify project level configuration simply by
+placing a `.isort.cfg` file at the root of your project. isort will look
+up to 25 directories up, from the file it is ran against, to find a
+project specific configuration.
+
+Or, if you prefer, you can add an `isort` or `tool:isort` section to
+your project's `setup.cfg` or `tox.ini` file with any desired settings.
+
+You can also add your desired settings under a `[tool.isort]` section in
+your `pyproject.toml` file.
+
+You can then override any of these settings by using command line
+arguments, or by passing in override values to the SortImports class.
+
+Finally, as of version 3.0 isort supports editorconfig files using the
+standard syntax defined here: <https://editorconfig.org/>
+
+Meaning you place any standard isort configuration parameters within a
+.editorconfig file under the `*.py` section and they will be honored.
+
+For a full list of isort settings and their meanings [take a look at the
+isort
+wiki](https://github.com/timothycrosley/isort/wiki/isort-Settings).
+
+Multi line output modes
+=======================
+
+You will notice above the \"multi\_line\_output\" setting. This setting
+defines how from imports wrap when they extend past the line\_length
+limit and has 6 possible settings:
+
+**0 - Grid**
+
+```python
+from third_party import (lib1, lib2, lib3,
+                         lib4, lib5, ...)
+```
+
+**1 - Vertical**
+
+```python
+from third_party import (lib1,
+                         lib2,
+                         lib3
+                         lib4,
+                         lib5,
+                         ...)
+```
+
+**2 - Hanging Indent**
+
+```python
+from third_party import \
+    lib1, lib2, lib3, \
+    lib4, lib5, lib6
+```
+
+**3 - Vertical Hanging Indent**
+
+```python
+from third_party import (
+    lib1,
+    lib2,
+    lib3,
+    lib4,
+)
+```
+
+**4 - Hanging Grid**
+
+```python
+from third_party import (
+    lib1, lib2, lib3, lib4,
+    lib5, ...)
+```
+
+**5 - Hanging Grid Grouped**
+
+```python
+from third_party import (
+    lib1, lib2, lib3, lib4,
+    lib5, ...
+)
+```
+
+**6 - Hanging Grid Grouped, No Trailing Comma**
+
+In Mode 5 isort leaves a single extra space to maintain consistency of
+output when a comma is added at the end. Mode 6 is the same - except
+that no extra space is maintained leading to the possibility of lines
+one character longer. You can enforce a trailing comma by using this in
+conjunction with `-tc` or `include_trailing_comma: True`.
+
+```python
+from third_party import (
+    lib1, lib2, lib3, lib4,
+    lib5
+)
+```
+
+**7 - NOQA**
+
+```python
+from third_party import lib1, lib2, lib3, ...  # NOQA
+```
+
+Alternatively, you can set `force_single_line` to `True` (`-sl` on the
+command line) and every import will appear on its own line:
+
+```python
+from third_party import lib1
+from third_party import lib2
+from third_party import lib3
+...
+```
+
+Note: to change the how constant indents appear - simply change the
+indent property with the following accepted formats:
+
+-   Number of spaces you would like. For example: 4 would cause standard
+    4 space indentation.
+-   Tab
+-   A verbatim string with quotes around it.
+
+For example:
+
+```python
+"    "
+```
+
+is equivalent to 4.
+
+For the import styles that use parentheses, you can control whether or
+not to include a trailing comma after the last import with the
+`include_trailing_comma` option (defaults to `False`).
+
+Intelligently Balanced Multi-line Imports
+=========================================
+
+As of isort 3.1.0 support for balanced multi-line imports has been
+added. With this enabled isort will dynamically change the import length
+to the one that produces the most balanced grid, while staying below the
+maximum import length defined.
+
+Example:
+
+```python
+from __future__ import (absolute_import, division,
+                        print_function, unicode_literals)
+```
+
+Will be produced instead of:
+
+```python
+from __future__ import (absolute_import, division, print_function,
+                        unicode_literals)
+```
+
+To enable this set `balanced_wrapping` to `True` in your config or pass
+the `-e` option into the command line utility.
+
+Custom Sections and Ordering
+============================
+
+You can change the section order with `sections` option from the default
+of:
+
+```ini
+FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
+```
+
+to your preference:
+
+```ini
+sections=FUTURE,STDLIB,FIRSTPARTY,THIRDPARTY,LOCALFOLDER
+```
+
+You also can define your own sections and their order.
+
+Example:
+
+```ini
+known_django=django
+known_pandas=pandas,numpy
+sections=FUTURE,STDLIB,DJANGO,THIRDPARTY,PANDAS,FIRSTPARTY,LOCALFOLDER
+```
+
+would create two new sections with the specified known modules.
+
+The `no_lines_before` option will prevent the listed sections from being
+split from the previous section by an empty line.
+
+Example:
+
+```ini
+sections=FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
+no_lines_before=LOCALFOLDER
+```
+
+would produce a section with both FIRSTPARTY and LOCALFOLDER modules
+combined.
+
+Auto-comment import sections
+============================
+
+Some projects prefer to have import sections uniquely titled to aid in
+identifying the sections quickly when visually scanning. isort can
+automate this as well. To do this simply set the
+`import_heading_{section_name}` setting for each section you wish to
+have auto commented - to the desired comment.
+
+For Example:
+
+```ini
+import_heading_stdlib=Standard Library
+import_heading_firstparty=My Stuff
+```
+
+Would lead to output looking like the following:
+
+```python
+# Standard Library
+import os
+import sys
+
+import django.settings
+
+# My Stuff
+import myproject.test
+```
+
+Ordering by import length
+=========================
+
+isort also makes it easy to sort your imports by length, simply by
+setting the `length_sort` option to `True`. This will result in the
+following output style:
+
+```python
+from evn.util import (
+    Pool,
+    Dict,
+    Options,
+    Constant,
+    DecayDict,
+    UnexpectedCodePath,
+)
+```
+
+It is also possible to opt-in to sorting imports by length for only
+specific sections by using `length_sort_` followed by the section name
+as a configuration item, e.g.:
+
+    length_sort_stdlib=1
+
+Skip processing of imports (outside of configuration)
+=====================================================
+
+To make isort ignore a single import simply add a comment at the end of
+the import line containing the text `isort:skip`:
+
+```python
+import module  # isort:skip
+```
+
+or:
+
+```python
+from xyz import (abc,  # isort:skip
+                 yo,
+                 hey)
+```
+
+To make isort skip an entire file simply add `isort:skip_file` to the
+module's doc string:
+
+```python
+""" my_module.py
+    Best module ever
+
+   isort:skip_file
+"""
+
+import b
+import a
+```
+
+Adding an import to multiple files
+==================================
+
+isort makes it easy to add an import statement across multiple files,
+while being assured it's correctly placed.
+
+From the command line:
+
+```bash
+isort -a "from __future__ import print_function" *.py
+```
+
+from within Kate:
+
+```
+ctrl+]
+```
+
+or:
+
+```
+menu > Python > Add Import
+```
+
+Removing an import from multiple files
+======================================
+
+isort also makes it easy to remove an import from multiple files,
+without having to be concerned with how it was originally formatted.
+
+From the command line:
+
+```bash
+isort -rm "os.system" *.py
+```
+
+from within Kate:
+
+```
+ctrl+shift+]
+```
+
+or:
+
+```
+menu > Python > Remove Import
+```
+
+Using isort to verify code
+==========================
+
+The `--check-only` option
+-------------------------
+
+isort can also be used to used to verify that code is correctly
+formatted by running it with `-c`. Any files that contain incorrectly
+sorted and/or formatted imports will be outputted to `stderr`.
+
+```bash
+isort **/*.py -c -vb
+
+SUCCESS: /home/timothy/Projects/Open_Source/isort/isort_kate_plugin.py Everything Looks Good!
+ERROR: /home/timothy/Projects/Open_Source/isort/isort/isort.py Imports are incorrectly sorted.
+```
+
+One great place this can be used is with a pre-commit git hook, such as
+this one by \@acdha:
+
+<https://gist.github.com/acdha/8717683>
+
+This can help to ensure a certain level of code quality throughout a
+project.
+
+Git hook
+--------
+
+isort provides a hook function that can be integrated into your Git
+pre-commit script to check Python code before committing.
+
+To cause the commit to fail if there are isort errors (strict mode),
+include the following in `.git/hooks/pre-commit`:
+
+```python
+#!/usr/bin/env python
+import sys
+from isort.hooks import git_hook
+
+sys.exit(git_hook(strict=True, modify=True))
+```
+
+If you just want to display warnings, but allow the commit to happen
+anyway, call `git_hook` without the strict parameter. If you want to
+display warnings, but not also fix the code, call `git_hook` without the
+modify parameter.
+
+Setuptools integration
+----------------------
+
+Upon installation, isort enables a `setuptools` command that checks
+Python files declared by your project.
+
+Running `python setup.py isort` on the command line will check the files
+listed in your `py_modules` and `packages`. If any warning is found, the
+command will exit with an error code:
+
+```bash
+$ python setup.py isort
+```
+
+Also, to allow users to be able to use the command without having to
+install isort themselves, add isort to the setup\_requires of your
+`setup()` like so:
+
+```python
+setup(
+    name="project",
+    packages=["project"],
+
+    setup_requires=[
+        "isort"
+    ]
+)
+```
+
+Security contact information ==========
+
+To report a security vulnerability, please use the [Tidelift security
+contact](https://tidelift.com/security). Tidelift will coordinate the
+fix and disclosure.
+
+Why isort?
+==========
+
+isort simply stands for import sort. It was originally called
+"sortImports" however I got tired of typing the extra characters and
+came to the realization camelCase is not pythonic.
+
+I wrote isort because in an organization I used to work in the manager
+came in one day and decided all code must have alphabetically sorted
+imports. The code base was huge - and he meant for us to do it by hand.
+However, being a programmer - I\'m too lazy to spend 8 hours mindlessly
+performing a function, but not too lazy to spend 16 hours automating it.
+I was given permission to open source sortImports and here we are :)
+
+------------------------------------------------------------------------
+
+Thanks and I hope you find isort useful!
+
+~Timothy Crosley
diff --git a/README.rst b/README.rst
deleted file mode 100644
index abc49334..00000000
--- a/README.rst
+++ /dev/null
@@ -1,675 +0,0 @@
-.. image:: https://raw.github.com/timothycrosley/isort/master/logo.png
-    :alt: isort
-
-########
-
-.. image:: https://badge.fury.io/py/isort.svg
-    :target: https://badge.fury.io/py/isort
-    :alt: PyPI version
-
-.. image:: https://travis-ci.org/timothycrosley/isort.svg?branch=master
-    :target: https://travis-ci.org/timothycrosley/isort
-    :alt: Build Status
-
-.. image:: https://codecov.io/gh/timothycrosley/isort/branch/develop/graph/badge.svg
-    :target: https://codecov.io/gh/timothycrosley/isort
-    :alt: Code coverage Status
-
-.. image:: https://img.shields.io/github/license/mashape/apistatus.svg
-    :target: https://pypi.org/project/hug/
-    :alt: License
-
-.. image:: https://badges.gitter.im/Join%20Chat.svg
-   :alt: Join the chat at https://gitter.im/timothycrosley/isort
-   :target: https://gitter.im/timothycrosley/isort?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-
-.. image:: https://pepy.tech/badge/isort
-    :alt: Downloads
-    :target: https://pepy.tech/project/isort
-
-isort your python imports for you so you don't have to.
-
-isort is a Python utility / library to sort imports alphabetically, and automatically separated into sections.
-It provides a command line utility, Python library and `plugins for various editors <https://github.com/timothycrosley/isort/wiki/isort-Plugins>`_ to quickly sort all your imports.
-It requires Python 3.5+ to run but supports formatting Python 2 code too.
-
-
-########
-
-`Get professionally supported isort with the Tidelift Subscription <https://tidelift.com/subscription/pkg/pypi-isort?utm_source=pypi-isort&utm_medium=referral&utm_campaign=readme>`_
-
-Professional support for isort is available as part of the `Tidelift
-Subscription`_.  Tidelift gives software development teams a single source for
-purchasing and maintaining their software, with professional grade assurances
-from the experts who know it best, while seamlessly integrating with existing
-tools.
-
-.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-isort?utm_source=pypi-isort&utm_medium=referral&utm_campaign=readme
-
-########
-
-.. image:: https://raw.github.com/timothycrosley/isort/develop/example.gif
-   :alt: Example Usage
-
-Before isort:
-
-.. code-block:: python
-
-    from my_lib import Object
-
-    print("Hey")
-
-    import os
-
-    from my_lib import Object3
-
-    from my_lib import Object2
-
-    import sys
-
-    from third_party import lib15, lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14
-
-    import sys
-
-    from __future__ import absolute_import
-
-    from third_party import lib3
-
-    print("yo")
-
-After isort:
-
-.. code-block:: python
-
-    from __future__ import absolute_import
-
-    import os
-    import sys
-
-    from third_party import (lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8,
-                             lib9, lib10, lib11, lib12, lib13, lib14, lib15)
-
-    from my_lib import Object, Object2, Object3
-
-    print("Hey")
-    print("yo")
-
-Installing isort
-================
-
-Installing isort is as simple as:
-
-.. code-block:: bash
-
-    pip install isort
-
-Install isort with requirements.txt support:
-
-.. code-block:: bash
-
-    pip install isort[requirements]
-
-Install isort with Pipfile support:
-
-.. code-block:: bash
-
-    pip install isort[pipfile]
-
-Install isort with both formats support:
-
-.. code-block:: bash
-
-    pip install isort[requirements,pipfile]
-
-Using isort
-===========
-
-**From the command line**:
-
-.. code-block:: bash
-
-    isort mypythonfile.py mypythonfile2.py
-
-or recursively:
-
-.. code-block:: bash
-
-    isort -rc .
-
-*which is equivalent to:*
-
-.. code-block:: bash
-
-    isort **/*.py
-
-or to see the proposed changes without applying them:
-
-.. code-block:: bash
-
-    isort mypythonfile.py --diff
-
-Finally, to atomically run isort against a project, only applying changes if they don't introduce syntax errors do:
-
-.. code-block:: bash
-
-    isort -rc --atomic .
-
-(Note: this is disabled by default as it keeps isort from being able to run against code written using a different version of Python)
-
-**From within Python**:
-
-.. code-block:: bash
-
-    from isort import SortImports
-
-    SortImports("pythonfile.py")
-
-or:
-
-.. code-block:: bash
-
-    from isort import SortImports
-
-    new_contents = SortImports(file_contents=old_contents).output
-
-**From within Kate:**
-
-.. code-block:: bash
-
-    ctrl+[
-
-or:
-
-.. code-block:: bash
-
-    menu > Python > Sort Imports
-
-Installing isort's Kate plugin
-==============================
-
-For KDE 4.13+ / Pate 2.0+:
-
-.. code-block:: bash
-
-    wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin.py --output-document ~/.kde/share/apps/kate/pate/isort_plugin.py
-    wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin_ui.rc --output-document ~/.kde/share/apps/kate/pate/isort_plugin_ui.rc
-    wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/katepart_isort.desktop --output-document ~/.kde/share/kde4/services/katepart_isort.desktop
-
-For all older versions:
-
-.. code-block:: bash
-
-    wget https://raw.github.com/timothycrosley/isort/master/kate_plugin/isort_plugin_old.py --output-document ~/.kde/share/apps/kate/pate/isort_plugin.py
-
-You will then need to restart kate and enable Python Plugins as well as the isort plugin itself.
-
-Installing isort's for your preferred text editor
-=================================================
-
-Several plugins have been written that enable to use isort from within a variety of text-editors.
-You can find a full list of them `on the isort wiki <https://github.com/timothycrosley/isort/wiki/isort-Plugins>`_.
-Additionally, I will enthusiastically accept pull requests that include plugins for other text editors
-and add documentation for them as I am notified.
-
-How does isort work?
-====================
-
-isort parses specified files for global level import lines (imports outside of try / except blocks, functions, etc..)
-and puts them all at the top of the file grouped together by the type of import:
-
-- Future
-- Python Standard Library
-- Third Party
-- Current Python Project
-- Explicitly Local (. before import, as in: ``from . import x``)
-- Custom Separate Sections (Defined by forced_separate list in configuration file)
-- Custom Sections (Defined by sections list in configuration file)
-
-Inside of each section the imports are sorted alphabetically. isort automatically removes duplicate python imports,
-and wraps long from imports to the specified line length (defaults to 79).
-
-When will isort not work?
-=========================
-
-If you ever have the situation where you need to have a try / except block in the middle of top-level imports or if
-your import order is directly linked to precedence.
-
-For example: a common practice in Django settings files is importing * from various settings files to form
-a new settings file. In this case if any of the imports change order you are changing the settings definition itself.
-
-However, you can configure isort to skip over just these files - or even to force certain imports to the top.
-
-Configuring isort
-=================
-
-If you find the default isort settings do not work well for your project, isort provides several ways to adjust
-the behavior.
-
-To configure isort for a single user create a ``~/.isort.cfg`` or ``$XDG_CONFIG_HOME/isort.cfg`` file:
-
-.. code-block:: ini
-
-    [settings]
-    line_length=120
-    force_to_top=file1.py,file2.py
-    skip=file3.py,file4.py
-    known_future_library=future,pies
-    known_standard_library=std,std2
-    known_third_party=randomthirdparty
-    known_first_party=mylib1,mylib2
-    indent='    '
-    multi_line_output=3
-    length_sort=1
-    forced_separate=django.contrib,django.utils
-    default_section=FIRSTPARTY
-    no_lines_before=LOCALFOLDER
-
-Additionally, you can specify project level configuration simply by placing a ``.isort.cfg`` file at the root of your
-project. isort will look up to 25 directories up, from the file it is ran against, to find a project specific configuration.
-
-Or, if you prefer, you can add an ``isort`` or ``tool:isort`` section to your project's ``setup.cfg`` or ``tox.ini`` file with any desired settings.
-
-You can also add your desired settings under a ``[tool.isort]`` section in your ``pyproject.toml`` file.
-
-You can then override any of these settings by using command line arguments, or by passing in override values to the
-SortImports class.
-
-Finally, as of version 3.0 isort supports editorconfig files using the standard syntax defined here:
-https://editorconfig.org/
-
-Meaning you place any standard isort configuration parameters within a .editorconfig file under the ``*.py`` section
-and they will be honored.
-
-For a full list of isort settings and their meanings `take a look at the isort wiki <https://github.com/timothycrosley/isort/wiki/isort-Settings>`_.
-
-Multi line output modes
-=======================
-
-You will notice above the "multi_line_output" setting. This setting defines how from imports wrap when they extend
-past the line_length limit and has 6 possible settings:
-
-**0 - Grid**
-
-.. code-block:: python
-
-    from third_party import (lib1, lib2, lib3,
-                             lib4, lib5, ...)
-
-**1 - Vertical**
-
-.. code-block:: python
-
-    from third_party import (lib1,
-                             lib2,
-                             lib3
-                             lib4,
-                             lib5,
-                             ...)
-
-**2 - Hanging Indent**
-
-.. code-block:: python
-
-    from third_party import \
-        lib1, lib2, lib3, \
-        lib4, lib5, lib6
-
-**3 - Vertical Hanging Indent**
-
-.. code-block:: python
-
-    from third_party import (
-        lib1,
-        lib2,
-        lib3,
-        lib4,
-    )
-
-**4 - Hanging Grid**
-
-.. code-block:: python
-
-    from third_party import (
-        lib1, lib2, lib3, lib4,
-        lib5, ...)
-
-**5 - Hanging Grid Grouped**
-
-.. code-block:: python
-
-    from third_party import (
-        lib1, lib2, lib3, lib4,
-        lib5, ...
-    )
-
-**6 - Hanging Grid Grouped, No Trailing Comma**
-
-In Mode 5 isort leaves a single extra space to maintain consistency of output when a comma is added at the end.
-Mode 6 is the same - except that no extra space is maintained leading to the possibility of lines one character longer.
-You can enforce a trailing comma by using this in conjunction with ``-tc`` or ``include_trailing_comma: True``.
-
-.. code-block:: python
-
-    from third_party import (
-        lib1, lib2, lib3, lib4,
-        lib5
-    )
-
-**7 - NOQA**
-
-.. code-block:: python
-
-    from third_party import lib1, lib2, lib3, ...  # NOQA
-
-Alternatively, you can set ``force_single_line`` to ``True`` (``-sl`` on the command line) and every import will appear on its
-own line:
-
-.. code-block:: python
-
-    from third_party import lib1
-    from third_party import lib2
-    from third_party import lib3
-    ...
-
-Note: to change the how constant indents appear - simply change the indent property with the following accepted formats:
-
-*   Number of spaces you would like. For example: 4 would cause standard 4 space indentation.
-*   Tab
-*   A verbatim string with quotes around it.
-
-For example:
-
-.. code-block:: python
-
-    "    "
-
-is equivalent to 4.
-
-For the import styles that use parentheses, you can control whether or not to
-include a trailing comma after the last import with the ``include_trailing_comma``
-option (defaults to ``False``).
-
-Intelligently Balanced Multi-line Imports
-=========================================
-
-As of isort 3.1.0 support for balanced multi-line imports has been added.
-With this enabled isort will dynamically change the import length to the one that produces the most balanced grid,
-while staying below the maximum import length defined.
-
-Example:
-
-.. code-block:: python
-
-    from __future__ import (absolute_import, division,
-                            print_function, unicode_literals)
-
-Will be produced instead of:
-
-.. code-block:: python
-
-    from __future__ import (absolute_import, division, print_function,
-                            unicode_literals)
-
-To enable this set ``balanced_wrapping`` to ``True`` in your config or pass the ``-e`` option into the command line utility.
-
-Custom Sections and Ordering
-============================
-
-You can change the section order with ``sections`` option from the default of:
-
-.. code-block:: ini
-
-    FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
-
-to your preference:
-
-.. code-block:: ini
-
-    sections=FUTURE,STDLIB,FIRSTPARTY,THIRDPARTY,LOCALFOLDER
-
-You also can define your own sections and their order.
-
-Example:
-
-.. code-block:: ini
-
-    known_django=django
-    known_pandas=pandas,numpy
-    sections=FUTURE,STDLIB,DJANGO,THIRDPARTY,PANDAS,FIRSTPARTY,LOCALFOLDER
-
-would create two new sections with the specified known modules.
-
-The ``no_lines_before`` option will prevent the listed sections from being split from the previous section by an empty line.
-
-Example:
-
-.. code-block:: ini
-
-   sections=FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
-   no_lines_before=LOCALFOLDER
-
-would produce a section with both FIRSTPARTY and LOCALFOLDER modules combined.
-
-Auto-comment import sections
-============================
-
-Some projects prefer to have import sections uniquely titled to aid in identifying the sections quickly
-when visually scanning. isort can automate this as well. To do this simply set the ``import_heading_{section_name}``
-setting for each section you wish to have auto commented - to the desired comment.
-
-For Example:
-
-.. code-block:: ini
-
-    import_heading_stdlib=Standard Library
-    import_heading_firstparty=My Stuff
-
-Would lead to output looking like the following:
-
-.. code-block:: python
-
-    # Standard Library
-    import os
-    import sys
-
-    import django.settings
-
-    # My Stuff
-    import myproject.test
-
-Ordering by import length
-=========================
-
-isort also makes it easy to sort your imports by length, simply by setting the ``length_sort`` option to ``True``.
-This will result in the following output style:
-
-.. code-block:: python
-
-    from evn.util import (
-        Pool,
-        Dict,
-        Options,
-        Constant,
-        DecayDict,
-        UnexpectedCodePath,
-    )
-
-It is also possible to opt-in to sorting imports by length for only specific
-sections by using ``length_sort_`` followed by the section name as a
-configuration item, e.g.::
-
-    length_sort_stdlib=1
-
-Skip processing of imports (outside of configuration)
-=====================================================
-
-To make isort ignore a single import simply add a comment at the end of the import line containing the text ``isort:skip``:
-
-.. code-block:: python
-
-    import module  # isort:skip
-
-or:
-
-.. code-block:: python
-
-    from xyz import (abc,  # isort:skip
-                     yo,
-                     hey)
-
-To make isort skip an entire file simply add ``isort:skip_file`` to the module's doc string:
-
-.. code-block:: python
-
-    """ my_module.py
-        Best module ever
-
-       isort:skip_file
-    """
-
-    import b
-    import a
-
-Adding an import to multiple files
-==================================
-
-isort makes it easy to add an import statement across multiple files, while being assured it's correctly placed.
-
-From the command line:
-
-.. code-block:: bash
-
-    isort -a "from __future__ import print_function" *.py
-
-from within Kate:
-
-.. code-block::
-
-    ctrl+]
-
-or:
-
-.. code-block::
-
-    menu > Python > Add Import
-
-Removing an import from multiple files
-======================================
-
-isort also makes it easy to remove an import from multiple files, without having to be concerned with how it was originally
-formatted.
-
-From the command line:
-
-.. code-block:: bash
-
-    isort -rm "os.system" *.py
-
-from within Kate:
-
-.. code-block::
-
-    ctrl+shift+]
-
-or:
-
-.. code-block::
-
-    menu > Python > Remove Import
-
-Using isort to verify code
-==========================
-
-The ``--check-only`` option
----------------------------
-
-isort can also be used to used to verify that code is correctly formatted by running it with ``-c``.
-Any files that contain incorrectly sorted and/or formatted imports will be outputted to ``stderr``.
-
-.. code-block:: bash
-
-    isort **/*.py -c -vb
-
-    SUCCESS: /home/timothy/Projects/Open_Source/isort/isort_kate_plugin.py Everything Looks Good!
-    ERROR: /home/timothy/Projects/Open_Source/isort/isort/isort.py Imports are incorrectly sorted.
-
-One great place this can be used is with a pre-commit git hook, such as this one by @acdha:
-
-https://gist.github.com/acdha/8717683
-
-This can help to ensure a certain level of code quality throughout a project.
-
-
-Git hook
---------
-
-isort provides a hook function that can be integrated into your Git pre-commit script to check
-Python code before committing.
-
-To cause the commit to fail if there are isort errors (strict mode), include the following in
-``.git/hooks/pre-commit``:
-
-.. code-block:: python
-
-    #!/usr/bin/env python
-    import sys
-    from isort.hooks import git_hook
-
-    sys.exit(git_hook(strict=True, modify=True))
-
-If you just want to display warnings, but allow the commit to happen anyway, call ``git_hook`` without
-the `strict` parameter. If you want to display warnings, but not also fix the code, call ``git_hook`` without
-the `modify` parameter.
-
-Setuptools integration
-----------------------
-
-Upon installation, isort enables a ``setuptools`` command that checks Python files
-declared by your project.
-
-Running ``python setup.py isort`` on the command line will check the files
-listed in your ``py_modules`` and ``packages``.  If any warning is found,
-the command will exit with an error code:
-
-.. code-block:: bash
-
-    $ python setup.py isort
-
-Also, to allow users to be able to use the command without having to install
-isort themselves, add isort to the setup_requires of your ``setup()`` like so:
-
-.. code-block:: python
-
-    setup(
-        name="project",
-        packages=["project"],
-
-        setup_requires=[
-            "isort"
-        ]
-    )
-
-Security contact information
-==========
-
-To report a security vulnerability, please use the `Tidelift security
-contact`_. Tidelift will coordinate the fix and disclosure.
-
-.. _Tidelift security contact: https://tidelift.com/security
-
-Why isort?
-==========
-
-isort simply stands for import sort. It was originally called "sortImports" however I got tired of typing the extra
-characters and came to the realization camelCase is not pythonic.
-
-I wrote isort because in an organization I used to work in the manager came in one day and decided all code must
-have alphabetically sorted imports. The code base was huge - and he meant for us to do it by hand. However, being a
-programmer - I'm too lazy to spend 8 hours mindlessly performing a function, but not too lazy to spend 16
-hours automating it. I was given permission to open source sortImports and here we are :)
-
---------------------------------------------
-
-Thanks and I hope you find isort useful!
-
-~Timothy Crosley
diff --git a/docs/contributing/1.-contributing-guide.md b/docs/contributing/1.-contributing-guide.md
new file mode 100644
index 00000000..d1b1cd62
--- /dev/null
+++ b/docs/contributing/1.-contributing-guide.md
@@ -0,0 +1,49 @@
+Contributing to isort
+========
+
+Looking for a useful open source project to contribute to?
+Want your contributions to be warmly welcomed and acknowledged?
+Welcome! You have found the right place.
+
+## Getting isort set up for local development
+The first step when contributing to any project is getting it set up on your local machine. isort aims to make this as simple as possible.
+
+Account Requirements:
+
+- [A valid GitHub account](https://github.com/join)
+
+Base System Requirements:
+
+- Python3.6+
+- poetry
+- bash or a bash compatible shell (should be auto-installed on Linux / Mac)
+
+Once you have verified that you system matches the base requirements you can start to get the project working by following these steps:
+
+1. [Fork the project on GitHub](https://github.com/timothycrosley/isort/fork).
+2. Clone your fork to your local file system:
+    `git clone https://github.com/$GITHUB_ACCOUNT/isort.git`
+3. `cd isort
+4. `poetry install`
+
+## Making a contribution
+Congrats! You're now ready to make a contribution! Use the following as a guide to help you reach a successful pull-request:
+
+1. Check the [issues page](https://github.com/timothycrosley/isort/issues) on GitHub to see if the task you want to complete is listed there.
+    - If it's listed there, write a comment letting others know you are working on it.
+    - If it's not listed in GitHub issues, go ahead and log a new issue. Then add a comment letting everyone know you have it under control.
+        - If you're not sure if it's something that is good for the main isort project and want immediate feedback, you can discuss it [here](https://gitter.im/timothycrosley/isort).
+2. Create an issue branch for your local work `git checkout -b issue/$ISSUE-NUMBER`.
+3. Do your magic here.
+4. Ensure your code matches the [HOPE-8 Coding Standard](https://github.com/hugapi/HOPE/blob/master/all/HOPE-8--Style-Guide-for-Hug-Code.md#hope-8----style-guide-for-hug-code) used by the project.
+5. Submit a pull request to the main project repository via GitHub.
+
+Thanks for the contribution! It will quickly get reviewed, and, once accepted, will result in your name being added to the acknowledgments list :).
+
+## Thank you!
+I can not tell you how thankful I am for the hard work done by isort contributors like *you*.
+
+Thank you!
+
+~Timothy Crosley
+
diff --git a/docs/contributing/2.-coding-standard.md b/docs/contributing/2.-coding-standard.md
new file mode 100644
index 00000000..85445e87
--- /dev/null
+++ b/docs/contributing/2.-coding-standard.md
@@ -0,0 +1,57 @@
+# HOPE 8 -- Style Guide for Hug Code
+
+|             |                                             |
+| ------------| ------------------------------------------- |
+| HOPE:       | 8                                           |
+| Title:      | Style Guide for Hug Code                    |
+| Author(s):  | Timothy Crosley <timothy.crosley@gmail.com> |
+| Status:     | Active                                      |
+| Type:       | Process                                     |
+| Created:    | 19-May-2019                                 |
+| Updated:    | 17-August-2019                                 |
+
+## Introduction
+
+This document gives coding conventions for the Hug code comprising the Hug core as well as all official interfaces, extensions, and plugins for the framework.
+Optionally, projects that use Hug are encouraged to follow this HOPE and link to it as a reference.
+
+## PEP 8 Foundation
+
+All guidelines in this document are in addition to those defined in Python's [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257](https://www.python.org/dev/peps/pep-0257/) guidelines.
+
+## Line Length
+
+Too short of lines discourage descriptive variable names where they otherwise make sense.
+Too long of lines reduce overall readability and make it hard to compare 2 files side by side.
+There is no perfect number: but for Hug, we've decided to cap the lines at 100 characters.
+
+## Descriptive Variable names
+
+Naming things is hard. Hug has a few strict guidelines on the usage of variable names, which hopefully will reduce some of the guesswork:
+- No one character variable names.
+    - Except for x, y, and z as coordinates.
+- It's not okay to override built-in functions.
+    - Except for `id`. Guido himself thought that shouldn't have been moved to the system module. It's too commonly used, and alternatives feel very artificial.
+- Avoid Acronyms, Abbreviations, or any other short forms - unless they are almost universally understand.
+
+## Adding new modules
+
+New modules added to the a project that follows the HOPE-8 standard should all live directly within the base `PROJECT_NAME/` directory without nesting. If the modules are meant only for internal use within the project, they should be prefixed with a leading underscore. For example, def _internal_function. Modules should contain a docstring at the top that gives a general explanation of the purpose and then restates the project's use of the MIT license.
+There should be a `tests/test_$MODULE_NAME.py` file created to correspond to every new module that contains test coverage for the module. Ideally, tests should be 1:1 (one test object per code object, one test method per code method) to the extent cleanly possible.
+
+## Automated Code Cleaners
+
+All code submitted to Hug should be formatted using Black and isort.
+Black should be run with the line length set to 100, and isort with Black compatible settings in place.
+
+## Automated Code Linting
+
+All code submitted to hug should run through the following tools:
+
+- Black and isort verification.
+- Flake8
+   - flake8-bugbear
+- Bandit
+- pep8-naming
+- vulture
+- safety
diff --git a/docs/contributing/3.-code-of-conduct.md b/docs/contributing/3.-code-of-conduct.md
new file mode 100644
index 00000000..a70f348f
--- /dev/null
+++ b/docs/contributing/3.-code-of-conduct.md
@@ -0,0 +1,88 @@
+# HOPE 11 -- Code of Conduct
+
+|             |                                             |
+| ------------| ------------------------------------------- |
+| HOPE:       | 11                                          |
+| Title:      | Code of Conduct                             |
+| Author(s):  | Timothy Crosley <timothy.crosley@gmail.com> |
+| Status:     | Active                                      |
+| Type:       | Process                                     |
+| Created:    | 17-August-2019                              |
+| Updated:    | 17-August-2019                              |
+
+## Abstract
+
+Defines the Code of Conduct for Hug and all related projects.
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting [timothy.crosley@gmail.com](mailto:timothy.crosley@gmail.com). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Confidentiality will be maintained
+with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/ACKNOWLEDGEMENTS.md b/docs/contributing/4.-acknowledgements.md
index d18b7036..d18b7036 100644
--- a/ACKNOWLEDGEMENTS.md
+++ b/docs/contributing/4.-acknowledgements.md
diff --git a/pyproject.toml b/pyproject.toml
index 9901ca3f..e8b3eb62 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ version = "4.3.21"
 description = "A Python utility / library to sort Python imports."
 authors = ["Timothy Crosley <timothy.crosley@gmail.com>"]
 license = "MIT"
-readme = "README.rst"
+readme = "README.md"
 repository = "https://github.com/timothycrosley/isort"
 website = "http://timothycrosley.github.io/isort/"
 keywords = ["Refactor", "Lint", "Imports", "Sort", "Clean"]