first pass

1 files changed, 70 insertions, 54 deletions

diff --git a/scripts/build_config_option_docs.py b/scripts/build_config_option_docs.py
index d7b0c643..3dbc41f5 100755
--- a/scripts/build_config_option_docs.py
+++ b/scripts/build_config_option_docs.py
@@ -1,7 +1,7 @@
 #! /bin/env python
 import os
-import textwrap
-from typing import Any, Generator, Iterable, Type
+from textwrap import dedent
+from typing import Any, Dict, Generator, Iterable, Optional, Type
 
 from isort._future import dataclass
 from isort.main import _build_arg_parser
@@ -27,61 +27,88 @@ parser = _build_arg_parser()
 
 
 @dataclass
-class ConfigOption:
-    name: str
-    type: Type = str
-    default: Any = ""
-    config_name: str = "**Not Supported**"
-    cli_options: Iterable[str] = ("**Not Supported**",)
-    description: str = "**No Description**"
-    example_section: str = ""
-    example_cfg: str = ""
-    example_pyproject_toml: str = ""
-    example_cli: str = ""
+class Example:
+    section_complete: str = ""
+    cfg: str = ""
+    pyproject_toml: str = ""
+    cli: str = ""
 
     def __post_init__(self):
-        if self.example_cfg or self.example_pyproject_toml or self.example_cli:
-            if self.example_cfg:
-                self.example_cfg = textwrap.dedent(
+        if self.cfg or self.pyproject_toml or self.cli:
+            if self.cfg:
+                self.cfg = dedent(
                     f"""
                     ### Example `.isort.cfg`
 
                     ```
-                    {self.example_cfg}
+                    {self.cfg}
                     ```
                     """
                 )
 
-            if self.example_pyproject_toml:
-                self.example_pyproject_toml = textwrap.dedent(
+            if self.pyproject_toml:
+                self.pyproject_toml = dedent(
                     f"""
                     ### Example `pyproject.toml`
 
                     ```
-                    {self.example_pyproject_toml}
+                    {self.pyproject_toml}
                     ```
                     """
                 )
 
-            if self.example_cli == "":
-                self.example_cli = textwrap.dedent(
+            if self.cli == "":
+                self.cli = dedent(
                     f"""
                     ### Example cli usage
-                    `{self.example_cli}`
+                    `{self.cli}`
                     """
                 )
 
-            self.example_section = f"""**Examples:**
+            self.section_complete = f"""**Examples:**
+
+{self.cfg}
+{self.pyproject_toml}
+{self.cli}"""
+
+        else:
+            self.section_complete = ""
+
+    def __str__(self):
+        return self.section_complete
+
+
+example_mapping: Dict[str, Example]
+example_mapping = {
+    "known_other": Example(
+        pyproject_toml="""[tool.isort]
+                    sections = ['FUTURE', 'STDLIB', 'THIRDPARTY', 'AIRFLOW', 'FIRSTPARTY', 'LOCALFOLDER']
+                    known_airflow = ['airflow']"""
+    )
+}
+
 
-{self.example_cfg}
-{self.example_pyproject_toml}
-{self.example_cli}"""
+@dataclass
+class ConfigOption:
+    name: str
+    type: Type = str
+    default: Any = ""
+    config_name: str = "**Not Supported**"
+    cli_options: Iterable[str] = tuple()
+    description: str = "**No Description**"
+    example: Optional[Example] = None
 
     def __str__(self):
         if self.name in IGNORED:
             return ""
 
-        cli_options = "\n- ".join(self.cli_options)
+        if self.cli_options == ():
+            cli_options = "**Not Supported**"
+        else:
+            cli_options = "- " + "\n- ".join(self.cli_options)
+
+        # new line if example otherwise nothing
+        example = f"\n{self.example}" if self.example else ""
         return f"""
 ## {human(self.name)}
 
@@ -92,10 +119,8 @@ class ConfigOption:
 **Python & Config File Name:** {self.config_name}{MD_NEWLINE}
 **CLI Flags:**
 
-- {cli_options}
-
-{self.example_section}
-"""
+{cli_options}
+{example}"""
 
 
 def human(name: str) -> str:
@@ -126,27 +151,14 @@ def config_options() -> Generator[ConfigOption, None, None]:
         # todo: refactor place for example params
         # needs to integrate with isort/settings/_Config
         # needs to integrate with isort/main/_build_arg_parser
-        if name != "known_other":
-            yield ConfigOption(
-                name=name,
-                type=type(default),
-                default=default_display,
-                config_name=name,
-                **extra_kwargs,
-            )
-        else:
-            yield ConfigOption(
-                name=name,
-                type=type(default),
-                default=default_display,
-                config_name=name,
-                example_pyproject_toml=textwrap.dedent(
-                    """[tool.isort]
-                    sections = ['FUTURE', 'STDLIB', 'THIRDPARTY', 'AIRFLOW', 'FIRSTPARTY', 'LOCALFOLDER']
-                    known_airflow = ['airflow']"""
-                ),
-                **extra_kwargs,
-            )
+        yield ConfigOption(
+            name=name,
+            type=type(default),
+            default=default_display,
+            config_name=name,
+            example=example_mapping.get(name, None),
+            **extra_kwargs,
+        )
 
     for name, cli in cli_actions.items():
         extra_kwargs = {}
@@ -159,7 +171,11 @@ def config_options() -> Generator[ConfigOption, None, None]:
             extra_kwargs["description"] = cli.help
 
         yield ConfigOption(
-            name=name, default=cli.default, cli_options=cli.option_strings, **extra_kwargs
+            name=name,
+            default=cli.default,
+            cli_options=cli.option_strings,
+            example=example_mapping.get(name, None),
+            **extra_kwargs,
         )