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.
1 # -*- coding: utf-8 -*-
3 # Configuration file for the Sphinx documentation builder.
5 # This file does only contain a selection of the most common options. For a
6 # full list see the documentation:
7 # http://www.sphinx-doc.org/en/stable/config
9 # -- Path setup --------------------------------------------------------------
11 # If extensions (or modules to document with autodoc) are in another directory,
12 # add these directories to sys.path here. If the directory is relative to the
13 # documentation root, use os.path.abspath to make it absolute, like shown here.
16 from pathlib import Path
21 from recommonmark.parser import CommonMarkParser
24 CURRENT_DIR = Path(__file__).parent
28 black_py = CURRENT_DIR / ".." / "black.py"
29 _version_re = re.compile(r"__version__\s+=\s+(?P<version>.*)")
30 with open(str(black_py), "r", encoding="utf8") as f:
31 version = _version_re.search(f.read()).group("version")
32 return str(ast.literal_eval(version))
35 def make_pypi_svg(version):
36 template = CURRENT_DIR / "_static" / "pypi_template.svg"
37 target = CURRENT_DIR / "_static" / "pypi.svg"
38 with open(str(template), "r", encoding="utf8") as f:
39 svg = string.Template(f.read()).substitute(version=version)
40 with open(str(target), "w", encoding="utf8") as f:
44 def make_filename(line):
45 non_letters = re.compile(r"[^a-z]+")
46 filename = line[3:].rstrip().lower()
47 filename = non_letters.sub("_", filename)
48 if filename.startswith("_"):
49 filename = filename[1:]
50 if filename.endswith("_"):
51 filename = filename[:-1]
52 return filename + ".md"
55 def generate_sections_from_readme():
56 target_dir = CURRENT_DIR / "_build" / "generated"
57 readme = CURRENT_DIR / ".." / "README.md"
58 shutil.rmtree(str(target_dir), ignore_errors=True)
59 target_dir.mkdir(parents=True)
62 target_dir = target_dir.relative_to(CURRENT_DIR)
63 with open(str(readme), "r", encoding="utf8") as f:
65 if line.startswith("## "):
66 if output is not None:
68 filename = make_filename(line)
69 output_path = CURRENT_DIR / filename
70 if output_path.is_symlink() or output_path.is_file():
72 output_path.symlink_to(target_dir / filename)
73 output = open(str(output_path), "w", encoding="utf8")
75 "[//]: # (NOTE: THIS FILE IS AUTOGENERATED FROM README.md)\n\n"
81 if line.startswith("##"):
87 # -- Project information -----------------------------------------------------
90 copyright = "2018, Łukasz Langa and contributors to Black"
91 author = "Łukasz Langa and contributors to Black"
93 # Autopopulate version
94 # The full version, including alpha/beta/rc tags.
95 release = get_version()
96 # The short X.Y version.
99 version = version.split(sp)[0]
100 make_pypi_svg(release)
101 generate_sections_from_readme()
104 # -- General configuration ---------------------------------------------------
106 # If your documentation needs a minimal Sphinx version, state it here.
108 # needs_sphinx = '1.0'
110 # Add any Sphinx extension module names here, as strings. They can be
111 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
113 extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon"]
115 # Add any paths that contain templates here, relative to this directory.
116 templates_path = ["_templates"]
118 source_parsers = {".md": CommonMarkParser}
120 # The suffix(es) of source filenames.
121 # You can specify multiple suffix as a list of string:
122 source_suffix = [".rst", ".md"]
124 # The master toctree document.
127 # The language for content autogenerated by Sphinx. Refer to documentation
128 # for a list of supported languages.
130 # This is also used if you do content translation via gettext catalogs.
131 # Usually you set "language" from the command line for these cases.
134 # List of patterns, relative to source directory, that match files and
135 # directories to ignore when looking for source files.
136 # This pattern also affects html_static_path and html_extra_path .
137 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
139 # The name of the Pygments (syntax highlighting) style to use.
140 pygments_style = "sphinx"
143 # -- Options for HTML output -------------------------------------------------
145 # The theme to use for HTML and HTML Help pages. See the documentation for
146 # a list of builtin themes.
148 html_theme = "alabaster"
160 html_theme_options = {
161 "show_related": False,
162 "description": "“Any color you like.”",
163 "github_button": True,
164 "github_user": "python",
165 "github_repo": "black",
166 "github_type": "star",
167 "show_powered_by": True,
168 "fixed_sidebar": True,
170 "travis_button": True,
174 # Add any paths that contain custom static files (such as style sheets) here,
175 # relative to this directory. They are copied after the builtin static files,
176 # so a file named "default.css" will overwrite the builtin "default.css".
177 html_static_path = ["_static"]
179 # Custom sidebar templates, must be a dictionary that maps document names
182 # The default sidebars (for documents that don't match any pattern) are
183 # defined by theme itself. Builtin themes are using these templates by
184 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
185 # 'searchbox.html']``.
190 # -- Options for HTMLHelp output ---------------------------------------------
192 # Output file base name for HTML help builder.
193 htmlhelp_basename = "blackdoc"
196 # -- Options for LaTeX output ------------------------------------------------
199 # The paper size ('letterpaper' or 'a4paper').
201 # 'papersize': 'letterpaper',
202 # The font size ('10pt', '11pt' or '12pt').
204 # 'pointsize': '10pt',
205 # Additional stuff for the LaTeX preamble.
208 # Latex figure (float) alignment
210 # 'figure_align': 'htbp',
213 # Grouping the document tree into LaTeX files. List of tuples
214 # (source start file, target name, title,
215 # author, documentclass [howto, manual, or own class]).
220 "Documentation for Black",
221 "Łukasz Langa and contributors to Black",
227 # -- Options for manual page output ------------------------------------------
229 # One entry per manual page. List of tuples
230 # (source start file, name, description, authors, manual section).
231 man_pages = [(master_doc, "black", "Documentation for Black", [author], 1)]
234 # -- Options for Texinfo output ----------------------------------------------
236 # Grouping the document tree into Texinfo files. List of tuples
237 # (source start file, target name, title, author,
238 # dir menu entry, description, category)
239 texinfo_documents = [
243 "Documentation for Black",
246 "The uncompromising Python code formatter",
252 # -- Options for Epub output -------------------------------------------------
254 # Bibliographic Dublin Core info.
257 epub_publisher = author
258 epub_copyright = copyright
260 # The unique identifier of the text. This can be a ISBN number
261 # or the project homepage.
263 # epub_identifier = ''
265 # A unique identification for the text.
269 # A list of files that should not be packed into the epub file.
270 epub_exclude_files = ["search.html"]
273 # -- Extension configuration -------------------------------------------------
275 autodoc_member_order = "bysource"
277 # -- Options for intersphinx extension ---------------------------------------
279 # Example configuration for intersphinx: refer to the Python standard library.
280 intersphinx_mapping = {"https://docs.python.org/3/": None}