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

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