| 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 |
} |