]> 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:

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