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)
+- [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)
 
-- 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
 

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 typing import Callable, List, Optional, Pattern, Tuple, Set
+from typing import Callable, Dict, List, Optional, Pattern, Tuple, Set
 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)
-    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]:
@@ -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.
     """
-    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:
-        LOG.info(f"Processing '{section.name}' from {section.src}")
         if section.name in processed_sections:
-            LOG.info(
+            LOG.warning(
                 f"Skipping '{section.name}' from '{section.src}' as it is a duplicate"
+                f" of a custom section from '{processed_sections[section.name].src}'"
             )
             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(
@@ -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)
-        processed_sections.add(section.name)
+        processed_sections[section.name] = section
         modified_files.add(target_path)