Debian Codegraph @

manual/conf.py

raw
1 # calibre documentation build configuration file, created by
2 # sphinx-quickstart.py on Sun Mar 23 01:23:55 2008.
3 #
4 # This file is execfile()d with the current directory set to its containing dir.
5 #
6 # The contents of this file are pickled, so don't put values in the namespace
7 # that aren't pickleable (module imports are okay, they're removed automatically).
8 #
9 # All configuration values have a default value; values that are commented out
10 # serve to show the default value.
11
12 import errno
13 import os
14 import sys
15 from datetime import date
16
17 # If your extensions are in another directory, add it here.
18 base = os.path.dirname(os.path.abspath(__file__))
19 sys.path.insert(0, os.path.dirname(base))
20 from setup import __appname__, __version__
21
22 sys.path.append(base)
23
24 import custom
25
26 import calibre.utils.img as cimg
27 from calibre.utils.localization import localize_website_link
28
29 del sys.path[0]
30
31 custom, cimg
32 # General configuration
33 # ---------------------
34
35 needs_sphinx = '1.2'
36
37 # Add any Sphinx extension module names here, as strings. They can be extensions
38 # coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
39 extensions = ['sphinx.ext.autodoc', 'custom', 'sidebar_toc', 'sphinx.ext.viewcode', 'sphinx.ext.extlinks']
40
41 # Add any paths that contain templates here, relative to this directory.
42 templates_path = ['templates']
43
44 # The suffix of source filenames.
45 source_suffix = {'.rst': 'restructuredtext'}
46
47 # The master toctree document.
48 master_doc = 'index' if tags.has('online') else 'simple_index' # noqa: F821
49 # kill the warning about index/simple_index not being in a toctree
50 exclude_patterns = ['simple_index.rst'] if master_doc == 'index' else ['index.rst']
51 exclude_patterns.append('cli-options-header.rst')
52 if tags.has('gettext'): # noqa: F821
53 # Do not exclude anything as the strings must be translated. This will
54 # generate a warning about the documents not being in a toctree, just ignore
55 # it.
56 exclude_patterns = []
57
58 # The language
59 language = os.environ.get('CALIBRE_OVERRIDE_LANG', 'en')
60
61
62 def generated_langs():
63 try:
64 return os.listdir(os.path.join(base, 'generated'))
65 except OSError as e:
66 if e.errno != errno.ENOENT:
67 raise
68 return ()
69
70
71 # ignore generated files in languages other than the language we are building for
72 ge = {'generated/' + x for x in generated_langs()} | {'generated/' + x for x in os.environ.get('ALL_USER_MANUAL_LANGUAGES', '').split()}
73 ge.discard('generated/' + language)
74 exclude_patterns += list(ge)
75 del ge
76
77 # General substitutions.
78 project = __appname__
79 copyright = 'Kovid Goyal'
80
81 # The default replacements for |version| and |release|, also used in various
82 # other places throughout the built documents.
83 #
84 # The short X.Y version.
85 version = __version__
86 # The full version, including alpha/beta/rc tags.
87 release = __version__
88
89 # There are two options for replacing |today|: either, you set today to some
90 # non-false value, then it is used:
91 # today = ''
92 # Else, today_fmt is used as the format for a strftime call.
93 today_fmt = '%B %d, %Y'
94
95 # List of documents that shouldn't be included in the build.
96 unused_docs = ['global', 'cli/global']
97
98 locale_dirs = ['locale/']
99 title = f'{__appname__} User Manual'
100 needs_localization = language not in {'en', 'eng'}
101 if needs_localization:
102 import gettext
103
104 try:
105 t = gettext.translation('simple_index', locale_dirs[0], [language])
106 except OSError:
107 pass
108 else:
109 title = t.gettext(title)
110
111 # If true, '()' will be appended to :func: etc. cross-reference text.
112 # add_function_parentheses = True
113
114 # If true, the current module name will be prepended to all description
115 # unit titles (such as .. function::).
116 # add_module_names = True
117
118 # If true, sectionauthor and moduleauthor directives will be shown in the
119 # output. They are ignored by default.
120 # show_authors = False
121
122 # The name of the Pygments (syntax highlighting) style to use.
123 pygments_style = 'sphinx'
124
125
126 # Options for HTML output
127 # -----------------------
128
129 # The style sheet to use for HTML and HTML Help pages. A file of that name
130 # must exist either in Sphinx' static/ path, or in one of the custom paths
131 # given in html_static_path.
132 html_theme = 'alabaster'
133 html_sidebars = {
134 '**': [
135 'about.html',
136 'searchbox.html',
137 'localtoc.html',
138 'relations.html',
139 ]
140 }
141 html_theme_options = {
142 'logo': 'logo.png',
143 'show_powered_by': False,
144 'fixed_sidebar': True,
145 'sidebar_collapse': True,
146 'github_button': False,
147 }
148
149 # The favicon
150 html_favicon = '../icons/favicon.ico'
151
152 # Add any paths that contain custom static files (such as style sheets) here,
153 # relative to this directory. They are copied after the built-in static files,
154 # so a file named "default.css" will overwrite the built-in "default.css".
155 html_static_path = ['resources', '../icons/favicon.ico']
156
157 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
158 # using the given strftime format.
159 html_last_updated_fmt = '%b %d, %Y'
160
161 # Overall title of the documentation
162 # html_title = title
163 html_short_title = _('Start')
164
165 from calibre.utils.localization import get_language
166
167 html_context = {}
168 html_context['other_languages'] = [(lc, get_language(lc)) for lc in os.environ.get('ALL_USER_MANUAL_LANGUAGES', '').split() if lc != language]
169
170
171 def sort_languages(x):
172 from calibre.utils.icu import sort_key
173
174 lc, name = x
175 if lc == language:
176 return ''
177 return sort_key(str(name))
178
179
180 website = 'https://calibre-ebook.com'
181 html_context['other_languages'].sort(key=sort_languages)
182 html_context['support_text'] = _('Support calibre')
183 html_context['support_tooltip'] = _('Contribute to support calibre development')
184 html_context['homepage_url'] = website
185 if needs_localization:
186 html_context['homepage_url'] = localize_website_link(html_context['homepage_url'])
187 extlinks = {
188 'website_base': (f'{website}/%s', None),
189 'website': (html_context['homepage_url'] + '/%s', None),
190 'download_file': (f'{website}/downloads/%s', '%s'),
191 }
192 del sort_languages, get_language
193
194 epub_author = 'Kovid Goyal'
195 epub_publisher = 'Kovid Goyal'
196 epub_copyright = f'© {date.today().year} Kovid Goyal'
197 epub_description = 'Comprehensive documentation for calibre'
198 epub_identifier = 'https://manual.calibre-ebook.com'
199 epub_scheme = 'url'
200 epub_uid = 'S54a88f8e9d42455e9c6db000e989225f'
201 epub_tocdepth = 4
202 epub_tocdup = True
203 epub_cover = ('epub_cover.jpg', 'epub_cover_template.html')
204 suppress_warnings = ['epub.duplicated_toc_entry']
205
206 # Custom sidebar templates, maps document names to template names.
207 # html_sidebars = {}
208
209 # Additional templates that should be rendered to pages, maps page names to
210 # template names.
211 # html_additional_pages = {}
212
213 html_use_modindex = False
214 html_use_index = False
215
216 # If true, the reST sources are included in the HTML build as _sources/<name>.
217 html_copy_source = True
218
219 # Output file base name for HTML help builder.
220 htmlhelp_basename = 'calibredoc'
221
222 html_use_opensearch = 'https://manual.calibre-ebook.com'
223
224 html_show_sphinx = False
225
226 # Options for LaTeX output
227 # ------------------------
228
229 # The paper size ('letter' or 'a4').
230 latex_paper_size = 'letter'
231
232 # The font size ('10pt', '11pt' or '12pt').
233 latex_font_size = '10pt'
234
235 # Grouping the document tree into LaTeX files. List of tuples
236 # (source start file, target name, title, author, document class [howto/manual]).
237 latex_documents = [(master_doc, 'calibre.tex', title, 'Kovid Goyal', 'manual', False)]
238
239 # Additional stuff for the LaTeX preamble.
240 # latex_preamble = ''
241
242 # Documents to append as an appendix to all manuals.
243 # latex_appendices = []
244
245 # If false, no module index is generated.
246 # latex_use_modindex = True
247
248 # we use lualatex as it is actively maintained and pdflatex and xelatex fail
249 # to render smart quotes and dashes
250 latex_engine = 'lualatex'
251 latex_logo = 'resources/logo.png'
252 latex_show_pagerefs = True
253 latex_show_urls = 'footnote'
254 latex_elements = {
255 'papersize': 'letterpaper',
256 'preamble': r'\renewcommand{\pageautorefname}{%s}' % _('page'), # noqa: UP031
257 }