Fix dealing with generated files in docs

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

diff --git a/docs/conf.py b/docs/conf.py
index 3343087cfbd02b7b9fe89dbb4412ce590096c1ae..8dd77b41d6149f4afa39b56390af1ada12052c8d 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,18 +17,15 @@ import re
 import string
 from typing import Callable, 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"
@@ -187,11 +184,9 @@ 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)
         modified_files.add(target_path)
@@ -200,7 +195,7 @@ def process_sections(
 # -- 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 +207,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 +215,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"]