Improve profile docs

2 files changed, 119 insertions, 0 deletions

diff --git a/docs/configuration/profiles.md b/docs/configuration/profiles.md
new file mode 100644
index 00000000..792ff988
--- /dev/null
+++ b/docs/configuration/profiles.md
@@ -0,0 +1,75 @@
+Built-in Profile for isort
+========
+
+The following profiles are built into isort to allow easy interoperability with
+common projects and code styles.
+
+To use any of the listed profiles, use `isort --profile PROFILE_NAME` from the command line, or `profile=PROFILE_NAME` in your configuration file.
+
+
+#black
+
+
+ - **multi_line_output**: `3`
+ - **include_trailing_comma**: `True`
+ - **force_grid_wrap**: `0`
+ - **use_parentheses**: `True`
+ - **ensure_newline_before_comments**: `True`
+
+#django
+
+
+ - **combine_as_imports**: `True`
+ - **include_trailing_comma**: `True`
+ - **multi_line_output**: `5`
+ - **line_length**: `79`
+
+#pycharm
+
+
+ - **multi_line_output**: `3`
+ - **force_grid_wrap**: `2`
+
+#google
+
+
+ - **force_single_line**: `True`
+ - **force_sort_within_sections**: `True`
+ - **lexicographical**: `True`
+ - **single_line_exclusions**: `('typing',)`
+
+#open_stack
+
+
+ - **force_single_line**: `True`
+ - **force_sort_within_sections**: `True`
+ - **lexicographical**: `True`
+
+#plone
+
+
+ - **force_alphabetical_sort**: `True`
+ - **force_single_line**: `True`
+ - **ines_after_imports**: `2`
+ - **line_length**: `200`
+
+#attrs
+
+
+ - **atomic**: `True`
+ - **force_grid_wrap**: `0`
+ - **include_trailing_comma**: `True`
+ - **lines_after_imports**: `2`
+ - **lines_between_types**: `1`
+ - **multi_line_output**: `3`
+ - **not_skip**: `'__init__.py'`
+ - **use_parentheses**: `True`
+
+#hug
+
+
+ - **multi_line_output**: `3`
+ - **include_trailing_comma**: `True`
+ - **force_grid_wrap**: `0`
+ - **use_parentheses**: `True`
+ - **line_length**: `100`
diff --git a/scripts/build_profile_docs.py b/scripts/build_profile_docs.py
new file mode 100755
index 00000000..e0a86f89
--- /dev/null
+++ b/scripts/build_profile_docs.py
@@ -0,0 +1,44 @@
+#! /bin/env python
+import os
+from typing import Any, Generator, Iterable, Type, Dict
+
+from isort._future import dataclass
+from isort.main import _build_arg_parser
+from isort.profiles import profiles
+from isort.settings import _DEFAULT_SETTINGS as config
+
+OUTPUT_FILE = os.path.abspath(
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), "../docs/configuration/profiles.md")
+)
+
+HEADER = """Built-in Profile for isort
+========
+
+The following profiles are built into isort to allow easy interoperability with
+common projects and code styles.
+
+To use any of the listed profiles, use `isort --profile PROFILE_NAME` from the command line, or `profile=PROFILE_NAME` in your configuration file.
+
+"""
+
+def format_profile(profile_name: str, profile: Dict[str, Any]) -> str:
+    options = "\n".join(f" - **{name}**: `{repr(value)}`" for name, value in profile.items())
+    return f"""
+#{profile_name}
+
+{profile.get('descripiton', '')}
+{options}
+"""
+
+
+def document_text() -> str:
+    return f"{HEADER}{''.join(format_profile(profile_name,  profile) for profile_name, profile in profiles.items())}"
+
+
+def write_document():
+    with open(OUTPUT_FILE, "w") as output_file:
+        output_file.write(document_text())
+
+
+if __name__ == "__main__":
+    write_document()