1extensions = ['sphinx.ext.autodoc', 'jaraco.packaging.sphinx', 'rst.linker']
2
3master_doc = "index"
4
5link_files = {
6    '../CHANGES.rst': dict(
7        using=dict(
8            BB='https://bitbucket.org',
9            GH='https://github.com',
10        ),
11        replace=[
12            dict(
13                pattern=r'(?<!\w)PR #(?P<pull>\d+)',
14                url='{package_url}/pull/{pull}',
15            ),
16            dict(
17                pattern=r'(?<!\w)(Issue )?#(?P<issue>\d+)',
18                url='{package_url}/issues/{issue}',
19            ),
20            dict(
21                pattern=r'BB Pull Request ?#(?P<bb_pull_request>\d+)',
22                url='{BB}/pypa/setuptools/pull-request/{bb_pull_request}',
23            ),
24            dict(
25                pattern=r'Distribute #(?P<distribute>\d+)',
26                url='{BB}/tarek/distribute/issue/{distribute}',
27            ),
28            dict(
29                pattern=r'Buildout #(?P<buildout>\d+)',
30                url='{GH}/buildout/buildout/issues/{buildout}',
31            ),
32            dict(
33                pattern=r'Old Setuptools #(?P<old_setuptools>\d+)',
34                url='http://bugs.python.org/setuptools/issue{old_setuptools}',
35            ),
36            dict(
37                pattern=r'Jython #(?P<jython>\d+)',
38                url='http://bugs.jython.org/issue{jython}',
39            ),
40            dict(
41                pattern=r'(Python #|bpo-)(?P<python>\d+)',
42                url='http://bugs.python.org/issue{python}',
43            ),
44            dict(
45                pattern=r'Interop #(?P<interop>\d+)',
46                url='{GH}/pypa/interoperability-peps/issues/{interop}',
47            ),
48            dict(
49                pattern=r'Pip #(?P<pip>\d+)',
50                url='{GH}/pypa/pip/issues/{pip}',
51            ),
52            dict(
53                pattern=r'Packaging #(?P<packaging>\d+)',
54                url='{GH}/pypa/packaging/issues/{packaging}',
55            ),
56            dict(
57                pattern=r'[Pp]ackaging (?P<packaging_ver>\d+(\.\d+)+)',
58                url='{GH}/pypa/packaging/blob/{packaging_ver}/CHANGELOG.rst',
59            ),
60            dict(
61                pattern=r'(?<![`/\w])PEP[- ](?P<pep_number>\d+)',
62                url='https://www.python.org/dev/peps/pep-{pep_number:0>4}/',
63            ),
64            dict(
65                pattern=r'setuptools_svn #(?P<setuptools_svn>\d+)',
66                url='{GH}/jaraco/setuptools_svn/issues/{setuptools_svn}',
67            ),
68            dict(
69                pattern=r'pypa/(?P<issue_repo>[\-\.\w]+)#(?P<issue_number>\d+)',
70                url='{GH}/pypa/{issue_repo}/issues/{issue_number}',
71            ),
72            dict(
73                pattern=r'pypa/(?P<commit_repo>[\-\.\w]+)@(?P<commit_number>[\da-f]+)',
74                url='{GH}/pypa/{commit_repo}/commit/{commit_number}',
75            ),
76            dict(
77                pattern=r'^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n',
78                with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
79            ),
80        ],
81    ),
82}
83
84# Be strict about any broken references:
85nitpicky = True
86
87# Include Python intersphinx mapping to prevent failures
88# jaraco/skeleton#51
89extensions += ['sphinx.ext.intersphinx']
90intersphinx_mapping = {
91    'python': ('https://docs.python.org/3', None),
92}
93
94intersphinx_mapping.update({
95    'pypa-build': ('https://pypa-build.readthedocs.io/en/latest/', None)
96})
97
98# Add support for linking usernames
99github_url = 'https://github.com'
100github_repo_org = 'pypa'
101github_repo_name = 'setuptools'
102github_repo_slug = f'{github_repo_org}/{github_repo_name}'
103github_repo_url = f'{github_url}/{github_repo_slug}'
104github_sponsors_url = f'{github_url}/sponsors'
105extlinks = {
106    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
107    'pypi': ('https://pypi.org/project/%s', '%s'),  # noqa: WPS323
108    'wiki': ('https://wikipedia.org/wiki/%s', '%s'),  # noqa: WPS323
109}
110extensions += ['sphinx.ext.extlinks']
111
112# Ref: https://github.com/python-attrs/attrs/pull/571/files\
113#      #diff-85987f48f1258d9ee486e3191495582dR82
114default_role = 'any'
115
116# HTML theme
117html_theme = 'furo'
118html_logo = "images/logo.svg"
119
120html_theme_options = {
121    "sidebar_hide_name": True,
122    "light_css_variables": {
123        "color-brand-primary": "#336790",  # "blue"
124        "color-brand-content": "#336790",
125    },
126    "dark_css_variables": {
127        "color-brand-primary": "#E5B62F",  # "yellow"
128        "color-brand-content": "#E5B62F",
129    },
130}
131
132# Add support for inline tabs
133extensions += ['sphinx_inline_tabs']
134
135# Support for distutils
136
137# Ref: https://stackoverflow.com/a/30624034/595220
138nitpick_ignore = [
139    ('c:func', 'SHGetSpecialFolderPath'),  # ref to MS docs
140    ('envvar', 'DISTUTILS_DEBUG'),  # undocumented
141    ('envvar', 'HOME'),  # undocumented
142    ('envvar', 'PLAT'),  # undocumented
143    ('py:attr', 'CCompiler.language_map'),  # undocumented
144    ('py:attr', 'CCompiler.language_order'),  # undocumented
145    ('py:class', 'distutils.dist.Distribution'),  # undocumented
146    ('py:class', 'distutils.extension.Extension'),  # undocumented
147    ('py:class', 'BorlandCCompiler'),  # undocumented
148    ('py:class', 'CCompiler'),  # undocumented
149    ('py:class', 'CygwinCCompiler'),  # undocumented
150    ('py:class', 'distutils.dist.DistributionMetadata'),  # undocumented
151    ('py:class', 'FileList'),  # undocumented
152    ('py:class', 'IShellLink'),  # ref to MS docs
153    ('py:class', 'MSVCCompiler'),  # undocumented
154    ('py:class', 'OptionDummy'),  # undocumented
155    ('py:class', 'UnixCCompiler'),  # undocumented
156    ('py:exc', 'CompileError'),  # undocumented
157    ('py:exc', 'DistutilsExecError'),  # undocumented
158    ('py:exc', 'DistutilsFileError'),  # undocumented
159    ('py:exc', 'LibError'),  # undocumented
160    ('py:exc', 'LinkError'),  # undocumented
161    ('py:exc', 'PreprocessError'),  # undocumented
162    ('py:func', 'distutils.CCompiler.new_compiler'),  # undocumented
163    # undocumented:
164    ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'),
165    ('py:func', 'distutils.file_util._copy_file_contents'),  # undocumented
166    ('py:func', 'distutils.log.debug'),  # undocumented
167    ('py:func', 'distutils.spawn.find_executable'),  # undocumented
168    ('py:func', 'distutils.spawn.spawn'),  # undocumented
169    # TODO: check https://docutils.rtfd.io in the future
170    ('py:mod', 'docutils'),  # there's no Sphinx site documenting this
171]
172
173# Allow linking objects on other Sphinx sites seamlessly:
174intersphinx_mapping.update(
175    python2=('https://docs.python.org/2', None),
176    python=('https://docs.python.org/3', None),
177)
178
179# Add support for the unreleased "next-version" change notes
180extensions += ['sphinxcontrib.towncrier']
181# Extension needs a path from here to the towncrier config.
182towncrier_draft_working_directory = '..'
183# Avoid an empty section for unpublished changes.
184towncrier_draft_include_empty = False
185
186extensions += ['jaraco.tidelift']
187
188# Add icons (aka "favicons") to documentation
189extensions += ['sphinx-favicon']
190html_static_path = ['images']  # should contain the folder with icons
191
192# List of dicts with <link> HTML attributes
193# static-file points to files in the html_static_path (href is computed)
194favicons = [
195    {  # "Catch-all" goes first, otherwise some browsers will overwrite
196        "rel": "icon",
197        "type": "image/svg+xml",
198        "static-file": "logo-symbol-only.svg",
199        "sizes": "any"
200    },
201    {  # Version with thicker strokes for better visibility at smaller sizes
202        "rel": "icon",
203        "type": "image/svg+xml",
204        "static-file": "favicon.svg",
205        "sizes": "16x16 24x24 32x32 48x48"
206    },
207    # rel="apple-touch-icon" does not support SVG yet
208]
209
210intersphinx_mapping['pip'] = 'https://pip.pypa.io/en/latest', None
211intersphinx_mapping['PyPUG'] = ('https://packaging.python.org/en/latest/', None)
212intersphinx_mapping['packaging'] = ('https://packaging.pypa.io/en/latest/', None)
213intersphinx_mapping['importlib-resources'] = (
214    'https://importlib-resources.readthedocs.io/en/latest', None
215)
216