Debian Codegraph @

docs/source/conf.py

raw
1 # (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
2 # All rights reserved.
3 #
4 # This software is provided without warranty under the terms of the BSD
5 # license included in LICENSE.txt and may be redistributed only under
6 # the conditions described in the aforementioned license. The license
7 # is also available online at http://www.enthought.com/licenses/BSD.txt
8 #
9 # Thanks for using Enthought open source!
10
11 # Traits documentation build configuration file, created by
12 # sphinx-quickstart on Tue Jul 22 10:52:03 2008.
13 #
14 # This file is execfile()d with the current directory set to its containing
15 # dir.
16 #
17 # The contents of this file are pickled, so don't put values in the namespace
18 # that aren't pickleable (module imports are okay, they're removed
19 # automatically).
20 #
21 # All configuration values have a default value; values that are commented out
22 # serve to show the default value.
23
24 import os
25 import sys
26
27
28 # The docset build will use slightly different formatting rules
29 BUILD_DOCSET = bool(os.environ.get("BUILD_DOCSET"))
30
31 # If your extensions are in another directory, add it here. If the directory
32 # is relative to the documentation root, use os.path.abspath to make it
33 # absolute, like shown here.
34 sys.path.append(os.path.abspath("../../"))
35
36
37 # General configuration
38 # ---------------------
39
40 # Add any Sphinx extension module names here, as strings. They can be
41 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
42 extensions = [
43 "sphinx.ext.autosummary",
44 "sphinx.ext.coverage",
45 "sphinx.ext.githubpages",
46 "sphinx.ext.intersphinx",
47 "sphinx.ext.napoleon",
48 "sphinx.ext.viewcode",
49 "sphinx_copybutton",
50 "traits.util.trait_documenter",
51 ]
52
53 # Add any paths that contain templates here, relative to this directory.
54 templates_path = ["_templates"]
55
56 # The suffix of source filenames.
57 source_suffix = ".rst"
58
59 # The master toctree document.
60 master_doc = "index"
61
62 # General substitutions.
63 project = "traits"
64 copyright = """\
65 (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
66 All rights reserved.
67 """
68
69 # The default replacements for |version| and |release|, also used in various
70 # other places throughout the built documents.
71 version_info = {}
72 traits_init_path = os.path.join("..", "..", "traits", "__init__.py")
73 with open(traits_init_path, "r", encoding="utf-8") as version_module:
74 version_code = compile(version_module.read(), "__init__.py", "exec")
75 exec(version_code, version_info)
76
77 # "release" is the full version string, including the bugfix portion and any
78 # modifiers. "version" is of the form "6.2" and is what's used in titles.
79 release = version_info["__version__"]
80 version = ".".join(release.split(".")[:2])
81
82 # There are two options for replacing |today|: either, you set today to some
83 # non-false value, then it is used:
84 # today = ''
85 # Else, today_fmt is used as the format for a strftime call.
86 today_fmt = "%B %d, %Y"
87
88 # List of documents that shouldn't be included in the build.
89 # unused_docs = []
90
91 # List of directories, relative to source directories, that shouldn't be
92 # searched for source files.
93 # exclude_dirs = []
94
95 # The reST default role (used for this markup: `text`) to use for all
96 # documents.
97 # default_role = None
98
99 # If true, '()' will be appended to :func: etc. cross-reference text.
100 # add_function_parentheses = True
101
102 # If true, the current module name will be prepended to all description
103 # unit titles (such as .. function::).
104 # add_module_names = True
105
106 # If true, sectionauthor and moduleauthor directives will be shown in the
107 # output. They are ignored by default.
108 # show_authors = False
109
110 # The name of the Pygments (syntax highlighting) style to use.
111 pygments_style = "sphinx"
112
113 # Options for the autodoc extension.
114 autodoc_default_options = {
115 "members": None,
116 }
117
118 autodoc_member_order = "bysource"
119
120 # Options for HTML output
121 # -----------------------
122
123 # Use enthought-sphinx-theme if available
124 try:
125 import enthought_sphinx_theme
126
127 html_theme_path = [enthought_sphinx_theme.theme_path]
128 html_theme = "enthought"
129
130 html_static_path = []
131 templates_path = []
132
133 except ImportError as exc:
134 import warnings
135
136 msg = """Can't find Enthought Sphinx Theme, using default.
137 Exception was: {}
138 Enthought Sphinx Theme can be installed from PyPI or EDM"""
139 warnings.warn(RuntimeWarning(msg.format(exc)))
140
141 # Use old defaults if enthought-sphinx-theme not available
142
143 # The name of an image file (within the static path) to place at the top
144 # of the sidebar.
145 html_logo = os.path.join("_static", "e-logo-rev.png")
146
147 # The name of an image file (within the static path) to use as favicon of
148 # the docs. This file should be a Windows icon file (.ico) being 16x16
149 # or 32x32 pixels large.
150 html_favicon = os.path.join("_static", "et.ico")
151
152 # The style sheet to use for HTML and HTML Help pages. A file of that name
153 # must exist either in Sphinx' static/ path, or in one of the custom paths
154 # given in html_static_path.
155 html_style = "default.css"
156
157 # Add any paths that contain custom static files (such as style sheets)
158 # here, relative to this directory. They are copied after the builtin
159 # static files, so a file named "default.css" will overwrite the builtin
160 # "default.css".
161 html_static_path = ["_static"]
162
163 # Add any paths that contain templates here, relative to this directory.
164 templates_path = ["_templates"]
165
166
167 # When using docset browsers like Dash and Zeal the side bar is redundant.
168 if BUILD_DOCSET:
169 html_theme_options = {"nosidebar": "true"}
170
171 # The name for this set of Sphinx documents. If None, it defaults to
172 # "<project> v<release> documentation".
173 html_title = "Traits {version} Documentation".format(version=version)
174
175 # A shorter title for the navigation bar. Default is the same as html_title.
176 # html_short_title = None
177
178 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
179 # using the given strftime format.
180 html_last_updated_fmt = "%b %d, %Y"
181
182 # If true, SmartyPants will be used to convert quotes and dashes to
183 # typographically correct entities.
184 html_use_smartypants = True
185
186 # Custom sidebar templates, maps document names to template names.
187 # html_sidebars = {}
188
189 # Additional templates that should be rendered to pages, maps page names to
190 # template names.
191 # html_additional_pages = {}
192
193 # If false, no index is generated.
194 html_use_index = True
195
196 # If true, the index is split into individual pages for each letter.
197 # html_split_index = False
198
199 # If true, the reST sources are included in the HTML build as _sources/<name>.
200 # html_copy_source = True
201
202 # If true, an OpenSearch description file will be output, and all pages will
203 # contain a <link> tag referring to it. The value of this option must be the
204 # base URL from which the finished HTML is served.
205 # html_use_opensearch = ''
206
207 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
208 # html_file_suffix = ''
209
210 # Output file base name for HTML help builder.
211 htmlhelp_basename = "Traitsdoc"
212
213
214 # Options for LaTeX output
215 # ------------------------
216
217 # The paper size ('letter' or 'a4').
218 # latex_paper_size = 'letter'
219
220 # The font size ('10pt', '11pt' or '12pt').
221 # latex_font_size = '10pt'
222
223 # Grouping the document tree into LaTeX files. List of tuples
224 # (source start file, target name, title, author,
225 # document class [howto/manual]).
226 latex_documents = [
227 (
228 "index",
229 "Traits.tex",
230 "Traits {version} User Manual".format(version=version),
231 "Enthought, Inc.",
232 "manual",
233 )
234 ]
235
236 # The name of an image file (relative to this directory) to place at the top of
237 # the title page.
238 # latex_logo = "enthought_logo.jpg"
239 latex_logo = "e-logo-rev.png"
240
241 # For "manual" documents, if this is true, then toplevel headings are parts,
242 # not chapters.
243 # latex_use_parts = False
244
245 # Additional stuff for the LaTeX preamble.
246 # latex_preamble = ''
247
248 # Documents to append as an appendix to all manuals.
249 # latex_appendices = []
250
251 # If false, no module index is generated.
252 # latex_use_modindex = True
253
254 # Options for Texinfo output
255 # --------------------------
256
257 # Grouping the document tree into Texinfo files. List of tuples
258 # (source start file, target name, title, author,
259 # dir menu entry, description, category)
260 texinfo_documents = [
261 (
262 "index",
263 "traits",
264 "Traits {version} User Manual".format(version=version),
265 "Enthought, Inc.",
266 "Traits",
267 "Explicitly typed attributes for Python.",
268 "Python",
269 )
270 ]
271
272 # Options for intersphinx extension
273 # ---------------------------------
274
275 intersphinx_mapping = {
276 "pyface": ("https://docs.enthought.com/pyface", None),
277 "python": ("https://docs.python.org/3", None),
278 "traitsui": ("https://docs.enthought.com/traitsui", None),
279 }