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

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