Primer: pyramid and sqlalchemy are now formatted with latest Black (#1736)

[etc/vim.git] / docs / conf.py

diff --git a/docs/conf.py b/docs/conf.py
index 3343087cfbd02b7b9fe89dbb4412ce590096c1ae..7381c9d6423f37a97148789e8c3c42cce3092f7f 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -15,20 +15,17 @@
 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 os
 import logging
 
 from pkg_resources import get_distribution
-from recommonmark.parser import CommonMarkParser
 
 logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
 
 LOG = logging.getLogger(__name__)
 
-# Get a relative path so logs printing out SRC isn't too long.
-CURRENT_DIR = Path(__file__).parent.relative_to(os.getcwd())
+CURRENT_DIR = Path(__file__).parent
 README = CURRENT_DIR / ".." / "README.md"
 REFERENCE_DIR = CURRENT_DIR / "reference"
 STATIC_DIR = CURRENT_DIR / "_static"
@@ -102,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]:
@@ -162,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(
@@ -187,20 +191,18 @@ def process_sections(
             contents = fix_headers(contents)
 
         with open(target_path, "w", encoding="utf-8") as f:
-            if section.src.suffix == ".md":
-                f.write(
-                    "[//]: # (NOTE: THIS FILE WAS AUTOGENERATED FROM"
-                    f" {section.src})\n\n"
-                )
+            if section.src.suffix == ".md" and section.src != target_path:
+                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)
 
 
 # -- Project information -----------------------------------------------------
 
 project = "Black"
-copyright = "2018, Łukasz Langa and contributors to Black"
+copyright = "2020, Łukasz Langa and contributors to Black"
 author = "Łukasz Langa and contributors to Black"
 
 # Autopopulate version
@@ -212,8 +214,7 @@ for sp in "abcfr":
     version = version.split(sp)[0]
 
 custom_sections = [
-    DocSection("the_black_code_style", CURRENT_DIR / "the_black_code_style.md",),
-    DocSection("pragmatism", CURRENT_DIR / "the_black_code_style.md",),
+    DocSection("the_black_code_style", CURRENT_DIR / "the_black_code_style.md"),
     DocSection("editor_integration", CURRENT_DIR / "editor_integration.md"),
     DocSection("blackd", CURRENT_DIR / "blackd.md"),
     DocSection("black_primer", CURRENT_DIR / "black_primer.md"),
@@ -221,28 +222,47 @@ custom_sections = [
     DocSection("change_log", CURRENT_DIR / ".." / "CHANGES.md"),
 ]
 
+# Sphinx complains when there is a source file that isn't referenced in any of the docs.
+# Since some sections autogenerated from the README are unused warnings will appear.
+#
+# Sections must be listed to what their name is when passed through make_filename().
+blocklisted_sections_from_readme = {
+    "license",
+    "pragmatism",
+    "testimonials",
+    "used_by",
+}
 
 make_pypi_svg(release)
 readme_sections = get_sections_from_readme()
+readme_sections = [
+    x for x in readme_sections if x.name not in blocklisted_sections_from_readme
+]
+
 process_sections(custom_sections, readme_sections)
 
 
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+needs_sphinx = "3.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "recommonmark",
+]
+
+# If you need extensions of a certain version or higher, list them here.
+needs_extensions = {"recommonmark": "0.5"}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-source_parsers = {".md": CommonMarkParser}
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 source_suffix = [".rst", ".md"]