Make doc generation a little smarter, update doc sections

diff --git a/docs/authors.md b/docs/authors.md
index 6a3a8d63f91ad7e6340ed1aefdf15295a3aab91e..a5349b4b9df74dd957706b4299f38e7012ba584f 100644 (file)
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -181,3 +181,4 @@ Multiple contributions by:
 - Yazdan
 - [Yngve Høiseth](mailto:yngve@hoiseth.net)
 - [Yurii Karabas](mailto:1998uriyyo@gmail.com)
 - Yazdan
 - [Yngve Høiseth](mailto:yngve@hoiseth.net)
 - [Yurii Karabas](mailto:1998uriyyo@gmail.com)

+- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)

diff --git a/docs/change_log.md b/docs/change_log.md
index 3cc8c40d8c6cfff58d1a1b9a476c79b023d422f3..5b7f08e101d05c7b621bc774a3f3b468c241ed0b 100644 (file)
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -9,15 +9,44 @@
 - re-implemented support for explicit trailing commas: now it works consistently within
   any bracket pair, including nested structures (#1288 and duplicates)
 
 - re-implemented support for explicit trailing commas: now it works consistently within
   any bracket pair, including nested structures (#1288 and duplicates)
 

-- reindent docstrings when reindenting code around it (#1053)
+- `Black` now reindents docstrings when reindenting code around it (#1053)

 
 

-- show colored diffs (#1266)
+- `Black` now shows colored diffs (#1266)

 
 

-- move to 'py3' tagged wheels (#1388)
+- `Black` is now packaged using 'py3' tagged wheels (#1388)

 
 

-- remove deprecated `--py36` option (#1236)
+- `Black` now supports Python 3.8 code, e.g. star expressions in return statements
+  (#1121)

 
 

-- add `--force-exclude` argument (#1032)
+- `Black` no longer normalizes capital R-string prefixes as those have a
+  community-accepted meaning (#1244)
+
+- `Black` now uses exit code 2 when specified configuration file doesn't exit (#1361)
+
+- `Black` now works on AWS Lambda (#1141)
+
+- added `--force-exclude` argument (#1032)
+
+- removed deprecated `--py36` option (#1236)
+
+- fixed `--diff` output when EOF is encountered (#526)
+
+- fixed `# fmt: off` handling around decorators (#560)
+
+- fixed unstable formatting with some `# type: ignore` comments (#1113)
+
+- fixed invalid removal on organizing brackets followed by indexing (#1575)
+
+- introduced `black-primer`, a CI tool that allows us to run regression tests against
+  existing open source users of Black (#1402)
+
+- introduced property-based fuzzing to our test suite based on Hypothesis and
+  Hypothersmith (#1566)
+
+- implemented experimental and disabled by default long string rewrapping (#1132),
+  hidden under a `--experimental-string-processing` flag while it's being worked on;
+  this is an undocumented and unsupported feature, you lose Internet points for
+  depending on it (#1609)

 
 #### Vim plugin
 
 
 #### Vim plugin
 

diff --git a/docs/conf.py b/docs/conf.py
index 8dd77b41d6149f4afa39b56390af1ada12052c8d..7381c9d6423f37a97148789e8c3c42cce3092f7f 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -15,7 +15,7 @@
 from pathlib import Path
 import re
 import string
 from pathlib import Path
 import re
 import string

-from typing import Callable, List, Optional, Pattern, Tuple, Set
+from typing import Callable, Dict, List, Optional, Pattern, Tuple, Set

 from dataclasses import dataclass
 import logging
 
 from dataclasses import dataclass
 import logging
 


@@ -99,7 +99,13 @@ def get_contents(section: DocSection) -> str:
         for lineno, line in enumerate(f, start=1):
             if lineno >= start_line and lineno < end_line:
                 contents.append(line)
         for lineno, line in enumerate(f, start=1):
             if lineno >= start_line and lineno < end_line:
                 contents.append(line)

-    return "".join(contents)
+    result = "".join(contents)
+    # Let's make Prettier happy with the amount of trailing newlines in the sections.
+    if result.endswith("\n\n"):
+        result = result[:-1]
+    if not result.endswith("\n"):
+        result = result + "\n"
+    return result

 
 
 def get_sections_from_readme() -> List[DocSection]:
 
 
 def get_sections_from_readme() -> List[DocSection]:


@@ -159,18 +165,19 @@ def process_sections(
     It processes custom sections before the README generated sections so sections in the
     README can be overwritten with custom options.
     """
     It processes custom sections before the README generated sections so sections in the
     README can be overwritten with custom options.
     """

-    processed_sections: Set[str] = set()
+    processed_sections: Dict[str, DocSection] = {}

     modified_files: Set[Path] = set()
     sections: List[DocSection] = custom_sections
     sections.extend(readme_sections)
     for section in sections:
     modified_files: Set[Path] = set()
     sections: List[DocSection] = custom_sections
     sections.extend(readme_sections)
     for section in sections:

-        LOG.info(f"Processing '{section.name}' from {section.src}")

         if section.name in processed_sections:
         if section.name in processed_sections:

-            LOG.info(
+            LOG.warning(

                 f"Skipping '{section.name}' from '{section.src}' as it is a duplicate"
                 f"Skipping '{section.name}' from '{section.src}' as it is a duplicate"

+                f" of a custom section from '{processed_sections[section.name].src}'"

             )
             continue
 
             )
             continue
 

+        LOG.info(f"Processing '{section.name}' from '{section.src}'")

         target_path: Path = CURRENT_DIR / section.get_out_filename()
         if target_path in modified_files:
             LOG.warning(
         target_path: Path = CURRENT_DIR / section.get_out_filename()
         if target_path in modified_files:
             LOG.warning(


@@ -188,7 +195,7 @@ def process_sections(
                 rel = section.src.resolve().relative_to(CURRENT_DIR.parent)
                 f.write(f'[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM {rel}"\n\n')
             f.write(contents)
                 rel = section.src.resolve().relative_to(CURRENT_DIR.parent)
                 f.write(f'[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM {rel}"\n\n')
             f.write(contents)

-        processed_sections.add(section.name)
+        processed_sections[section.name] = section

         modified_files.add(target_path)
 
 
         modified_files.add(target_path)