]> git.madduck.net Git - etc/vim.git/blob - 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:

6421d53e0dd5bfed1646d02f35fdf98fc804b050
[etc/vim.git] / docs / conf.py
1 # -*- coding: utf-8 -*-
2 #
3 # Configuration file for the Sphinx documentation builder.
4 #
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
8
9 # -- Path setup --------------------------------------------------------------
10
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.
14 #
15 import ast
16 from pathlib import Path
17 import re
18 import shutil
19 import string
20
21 from recommonmark.parser import CommonMarkParser
22
23
24 CURRENT_DIR = Path(__file__).parent
25
26
27 def get_version():
28     import sys
29
30     sys.path.append(str(CURRENT_DIR.parent))
31     from _version import get_versions
32
33     v = get_versions()
34     return v.get("closest-tag", v["version"])
35
36
37 def make_pypi_svg(version):
38     template = CURRENT_DIR / "_static" / "pypi_template.svg"
39     target = CURRENT_DIR / "_static" / "pypi.svg"
40     with open(str(template), "r", encoding="utf8") as f:
41         svg = string.Template(f.read()).substitute(version=version)
42     with open(str(target), "w", encoding="utf8") as f:
43         f.write(svg)
44
45
46 def make_filename(line):
47     non_letters = re.compile(r"[^a-z]+")
48     filename = line[3:].rstrip().lower()
49     filename = non_letters.sub("_", filename)
50     if filename.startswith("_"):
51         filename = filename[1:]
52     if filename.endswith("_"):
53         filename = filename[:-1]
54     return filename + ".md"
55
56
57 def generate_sections_from_readme():
58     target_dir = CURRENT_DIR / "_build" / "generated"
59     readme = CURRENT_DIR / ".." / "README.md"
60     shutil.rmtree(str(target_dir), ignore_errors=True)
61     target_dir.mkdir(parents=True)
62
63     output = None
64     target_dir = target_dir.relative_to(CURRENT_DIR)
65     with open(str(readme), "r", encoding="utf8") as f:
66         for line in f:
67             if line.startswith("## "):
68                 if output is not None:
69                     output.close()
70                 filename = make_filename(line)
71                 output_path = CURRENT_DIR / filename
72                 if output_path.is_symlink() or output_path.is_file():
73                     output_path.unlink()
74                 output_path.symlink_to(target_dir / filename)
75                 output = open(str(output_path), "w", encoding="utf8")
76                 output.write(
77                     "[//]: # (NOTE: THIS FILE IS AUTOGENERATED FROM README.md)\n\n"
78                 )
79
80             if output is None:
81                 continue
82
83             if line.startswith("##"):
84                 line = line[1:]
85
86             output.write(line)
87
88
89 # -- Project information -----------------------------------------------------
90
91 project = "Black"
92 copyright = "2018, Łukasz Langa and contributors to Black"
93 author = "Łukasz Langa and contributors to Black"
94
95 # Autopopulate version
96 # The full version, including alpha/beta/rc tags.
97 release = get_version()
98 # The short X.Y version.
99 version = release
100 for sp in "abcfr":
101     version = version.split(sp)[0]
102 make_pypi_svg(release)
103 generate_sections_from_readme()
104
105
106 # -- General configuration ---------------------------------------------------
107
108 # If your documentation needs a minimal Sphinx version, state it here.
109 #
110 # needs_sphinx = '1.0'
111
112 # Add any Sphinx extension module names here, as strings. They can be
113 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
114 # ones.
115 extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon"]
116
117 # Add any paths that contain templates here, relative to this directory.
118 templates_path = ["_templates"]
119
120 source_parsers = {".md": CommonMarkParser}
121
122 # The suffix(es) of source filenames.
123 # You can specify multiple suffix as a list of string:
124 source_suffix = [".rst", ".md"]
125
126 # The master toctree document.
127 master_doc = "index"
128
129 # The language for content autogenerated by Sphinx. Refer to documentation
130 # for a list of supported languages.
131 #
132 # This is also used if you do content translation via gettext catalogs.
133 # Usually you set "language" from the command line for these cases.
134 language = None
135
136 # List of patterns, relative to source directory, that match files and
137 # directories to ignore when looking for source files.
138 # This pattern also affects html_static_path and html_extra_path .
139 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
140
141 # The name of the Pygments (syntax highlighting) style to use.
142 pygments_style = "sphinx"
143
144
145 # -- Options for HTML output -------------------------------------------------
146
147 # The theme to use for HTML and HTML Help pages.  See the documentation for
148 # a list of builtin themes.
149 #
150 html_theme = "alabaster"
151
152 html_sidebars = {
153     "**": [
154         "about.html",
155         "navigation.html",
156         "relations.html",
157         "sourcelink.html",
158         "searchbox.html",
159     ]
160 }
161
162 html_theme_options = {
163     "show_related": False,
164     "description": "“Any color you like.”",
165     "github_button": True,
166     "github_user": "psf",
167     "github_repo": "black",
168     "github_type": "star",
169     "show_powered_by": True,
170     "fixed_sidebar": True,
171     "logo": "logo2.png",
172     "travis_button": True,
173 }
174
175
176 # Add any paths that contain custom static files (such as style sheets) here,
177 # relative to this directory. They are copied after the builtin static files,
178 # so a file named "default.css" will overwrite the builtin "default.css".
179 html_static_path = ["_static"]
180
181 # Custom sidebar templates, must be a dictionary that maps document names
182 # to template names.
183 #
184 # The default sidebars (for documents that don't match any pattern) are
185 # defined by theme itself.  Builtin themes are using these templates by
186 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
187 # 'searchbox.html']``.
188 #
189 # html_sidebars = {}
190
191
192 # -- Options for HTMLHelp output ---------------------------------------------
193
194 # Output file base name for HTML help builder.
195 htmlhelp_basename = "blackdoc"
196
197
198 # -- Options for LaTeX output ------------------------------------------------
199
200 latex_elements = {
201     # The paper size ('letterpaper' or 'a4paper').
202     #
203     # 'papersize': 'letterpaper',
204     # The font size ('10pt', '11pt' or '12pt').
205     #
206     # 'pointsize': '10pt',
207     # Additional stuff for the LaTeX preamble.
208     #
209     # 'preamble': '',
210     # Latex figure (float) alignment
211     #
212     # 'figure_align': 'htbp',
213 }
214
215 # Grouping the document tree into LaTeX files. List of tuples
216 # (source start file, target name, title,
217 #  author, documentclass [howto, manual, or own class]).
218 latex_documents = [
219     (
220         master_doc,
221         "black.tex",
222         "Documentation for Black",
223         "Łukasz Langa and contributors to Black",
224         "manual",
225     )
226 ]
227
228
229 # -- Options for manual page output ------------------------------------------
230
231 # One entry per manual page. List of tuples
232 # (source start file, name, description, authors, manual section).
233 man_pages = [(master_doc, "black", "Documentation for Black", [author], 1)]
234
235
236 # -- Options for Texinfo output ----------------------------------------------
237
238 # Grouping the document tree into Texinfo files. List of tuples
239 # (source start file, target name, title, author,
240 #  dir menu entry, description, category)
241 texinfo_documents = [
242     (
243         master_doc,
244         "Black",
245         "Documentation for Black",
246         author,
247         "Black",
248         "The uncompromising Python code formatter",
249         "Miscellaneous",
250     )
251 ]
252
253
254 # -- Options for Epub output -------------------------------------------------
255
256 # Bibliographic Dublin Core info.
257 epub_title = project
258 epub_author = author
259 epub_publisher = author
260 epub_copyright = copyright
261
262 # The unique identifier of the text. This can be a ISBN number
263 # or the project homepage.
264 #
265 # epub_identifier = ''
266
267 # A unique identification for the text.
268 #
269 # epub_uid = ''
270
271 # A list of files that should not be packed into the epub file.
272 epub_exclude_files = ["search.html"]
273
274
275 # -- Extension configuration -------------------------------------------------
276
277 autodoc_member_order = "bysource"
278
279 # -- Options for intersphinx extension ---------------------------------------
280
281 # Example configuration for intersphinx: refer to the Python standard library.
282 intersphinx_mapping = {"https://docs.python.org/3/": None}