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

Make Prettier preserve line ending type (#2244)
[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 from pathlib import Path
16 import string
17
18 from pkg_resources import get_distribution
19
20 CURRENT_DIR = Path(__file__).parent
21
22
23 def make_pypi_svg(version: str) -> None:
24     template: Path = CURRENT_DIR / "_static" / "pypi_template.svg"
25     target: Path = CURRENT_DIR / "_static" / "pypi.svg"
26     with open(str(template), "r", encoding="utf8") as f:
27         svg: str = string.Template(f.read()).substitute(version=version)
28     with open(str(target), "w", encoding="utf8") as f:
29         f.write(svg)
30
31
32 # -- Project information -----------------------------------------------------
33
34 project = "Black"
35 copyright = "2018-Present, Łukasz Langa and contributors to Black"
36 author = "Łukasz Langa and contributors to Black"
37
38 # Autopopulate version
39 # The version, including alpha/beta/rc tags, but not commit hash and datestamps
40 release = get_distribution("black").version.split("+")[0]
41 # The short X.Y version.
42 version = release
43 for sp in "abcfr":
44     version = version.split(sp)[0]
45
46 make_pypi_svg(release)
47
48
49 # -- General configuration ---------------------------------------------------
50
51 # If your documentation needs a minimal Sphinx version, state it here.
52 needs_sphinx = "3.0"
53
54 # Add any Sphinx extension module names here, as strings. They can be
55 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
56 # ones.
57 extensions = [
58     "sphinx.ext.autodoc",
59     "sphinx.ext.intersphinx",
60     "sphinx.ext.napoleon",
61     "myst_parser",
62     "sphinxcontrib.programoutput",
63     "sphinx_copybutton",
64 ]
65
66 # If you need extensions of a certain version or higher, list them here.
67 needs_extensions = {"myst_parser": "0.13.7"}
68
69 # Add any paths that contain templates here, relative to this directory.
70 templates_path = ["_templates"]
71
72 # The suffix(es) of source filenames.
73 # You can specify multiple suffix as a list of string:
74 source_suffix = [".rst", ".md"]
75
76 # The master toctree document.
77 master_doc = "index"
78
79 # The language for content autogenerated by Sphinx. Refer to documentation
80 # for a list of supported languages.
81 #
82 # This is also used if you do content translation via gettext catalogs.
83 # Usually you set "language" from the command line for these cases.
84 language = None
85
86 # List of patterns, relative to source directory, that match files and
87 # directories to ignore when looking for source files.
88 # This pattern also affects html_static_path and html_extra_path .
89
90 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
91
92 # The name of the Pygments (syntax highlighting) style to use.
93 pygments_style = "sphinx"
94
95 # We need headers to be linkable to so ask MyST-Parser to autogenerate anchor IDs for
96 # headers up to and including level 3.
97 myst_heading_anchors = 3
98
99 # Prettier support formatting some MyST syntax but not all, so let's disable the
100 # unsupported yet still enabled by default ones.
101 myst_disable_syntax = [
102     "myst_block_break",
103     "myst_line_comment",
104     "math_block",
105 ]
106
107 # -- Options for HTML output -------------------------------------------------
108
109 # The theme to use for HTML and HTML Help pages.  See the documentation for
110 # a list of builtin themes.
111 #
112 html_theme = "alabaster"
113
114 html_sidebars = {
115     "**": [
116         "about.html",
117         "navigation.html",
118         "relations.html",
119         "searchbox.html",
120     ]
121 }
122
123 html_theme_options = {
124     "show_related": False,
125     "description": "“Any color you like.”",
126     "github_button": True,
127     "github_user": "psf",
128     "github_repo": "black",
129     "github_type": "star",
130     "show_powered_by": True,
131     "fixed_sidebar": True,
132     "logo": "logo2.png",
133 }
134
135
136 # Add any paths that contain custom static files (such as style sheets) here,
137 # relative to this directory. They are copied after the builtin static files,
138 # so a file named "default.css" will overwrite the builtin "default.css".
139 html_static_path = ["_static"]
140
141 # Custom sidebar templates, must be a dictionary that maps document names
142 # to template names.
143 #
144 # The default sidebars (for documents that don't match any pattern) are
145 # defined by theme itself.  Builtin themes are using these templates by
146 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
147 # 'searchbox.html']``.
148 #
149 # html_sidebars = {}
150
151
152 # -- Options for HTMLHelp output ---------------------------------------------
153
154 # Output file base name for HTML help builder.
155 htmlhelp_basename = "blackdoc"
156
157
158 # -- Options for LaTeX output ------------------------------------------------
159
160 # Grouping the document tree into LaTeX files. List of tuples
161 # (source start file, target name, title,
162 #  author, documentclass [howto, manual, or own class]).
163 latex_documents = [
164     (
165         master_doc,
166         "black.tex",
167         "Documentation for Black",
168         "Łukasz Langa and contributors to Black",
169         "manual",
170     )
171 ]
172
173
174 # -- Options for manual page output ------------------------------------------
175
176 # One entry per manual page. List of tuples
177 # (source start file, name, description, authors, manual section).
178 man_pages = [(master_doc, "black", "Documentation for Black", [author], 1)]
179
180
181 # -- Options for Texinfo output ----------------------------------------------
182
183 # Grouping the document tree into Texinfo files. List of tuples
184 # (source start file, target name, title, author,
185 #  dir menu entry, description, category)
186 texinfo_documents = [
187     (
188         master_doc,
189         "Black",
190         "Documentation for Black",
191         author,
192         "Black",
193         "The uncompromising Python code formatter",
194         "Miscellaneous",
195     )
196 ]
197
198
199 # -- Options for Epub output -------------------------------------------------
200
201 # Bibliographic Dublin Core info.
202 epub_title = project
203 epub_author = author
204 epub_publisher = author
205 epub_copyright = copyright
206
207 # The unique identifier of the text. This can be a ISBN number
208 # or the project homepage.
209 #
210 # epub_identifier = ''
211
212 # A unique identification for the text.
213 #
214 # epub_uid = ''
215
216 # A list of files that should not be packed into the epub file.
217 epub_exclude_files = ["search.html"]
218
219
220 # -- Extension configuration -------------------------------------------------
221
222 autodoc_member_order = "bysource"
223
224 # -- Options for intersphinx extension ---------------------------------------
225
226 # Example configuration for intersphinx: refer to the Python standard library.
227 intersphinx_mapping = {"https://docs.python.org/3/": None}