]>
git.madduck.net Git - etc/vim.git/blobdiff - docs/conf.py
madduck's git repository
Every one of the projects in this repository is available at the canonical
URL git://git.madduck.net/madduck/pub/<projectpath> — see
each project's metadata for the exact URL.
All patches and comments are welcome. Please squash your changes to logical
commits before using git-format-patch and git-send-email to
patches@ git. madduck. net .
If you'd read over the Git project's submission guidelines and adhered to them,
I'd be especially grateful.
SSH access, as well as push access can be individually
arranged .
If you use my repositories frequently, consider adding the following
snippet to ~/.gitconfig and using the third clone URL listed for each
project:
[url "git://git.madduck.net/madduck/"]
insteadOf = madduck:
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
from dataclasses import dataclass
import logging
from pkg_resources import get_distribution
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__)
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"
README = CURRENT_DIR / ".." / "README.md"
REFERENCE_DIR = CURRENT_DIR / "reference"
STATIC_DIR = CURRENT_DIR / "_static"
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]:
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:
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}'"
+ 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(
contents = fix_headers(contents)
with open(target_path, "w", encoding="utf-8") as f:
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')
- processed_sections.add(section.name)
+ processed_sections[section.name] = section
modified_files.add(target_path)
# -- Project information -----------------------------------------------------
project = "Black"
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
author = "Łukasz Langa and contributors to Black"
# Autopopulate version
version = version.split(sp)[0]
custom_sections = [
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"),
DocSection("editor_integration", CURRENT_DIR / "editor_integration.md"),
DocSection("blackd", CURRENT_DIR / "blackd.md"),
DocSection("black_primer", CURRENT_DIR / "black_primer.md"),
DocSection("change_log", CURRENT_DIR / ".." / "CHANGES.md"),
]
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()
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.
process_sections(custom_sections, readme_sections)
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# 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"]
# 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"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = [".rst", ".md"]
projects / etc / vim.git / blobdiff