DISPATCH
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/master/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 # import os
16 # import sys
17 # sys.path.insert(0, os.path.abspath('.'))
18 
19 
20 # -- Project information -----------------------------------------------------
21 
22 project = 'DISPATCH'
23 copyright = u'2019, Åke Nordlund'
24 author = u'Åke Nordlund'
25 
26 # The short X.Y version
27 version = ''
28 # The full version, including alpha/beta/rc tags
29 release = ''
30 
31 
32 # -- General configuration ---------------------------------------------------
33 
34 # If your documentation needs a minimal Sphinx version, state it here.
35 #
36 # needs_sphinx = '1.0'
37 
38 # Add any Sphinx extension module names here, as strings. They can be
39 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40 # ones.
41 extensions = [
42  'nbsphinx',
43  'sphinx.ext.todo',
44  'sphinx.ext.mathjax',
45  'sphinx.ext.ifconfig',
46 ]
47 
48 # Add any paths that contain templates here, relative to this directory.
49 templates_path = ['_templates']
50 
51 # The suffix(es) of source filenames.
52 # You can specify multiple suffix as a list of string:
53 #
54 source_suffix = ['.rst', '.md']
55 # source_suffix = '.rst'
56 
57 # The master toctree document.
58 master_doc = 'index'
59 
60 # The language for content autogenerated by Sphinx. Refer to documentation
61 # for a list of supported languages.
62 #
63 # This is also used if you do content translation via gettext catalogs.
64 # Usually you set "language" from the command line for these cases.
65 language = None
66 
67 # List of patterns, relative to source directory, that match files and
68 # directories to ignore when looking for source files.
69 # This pattern also affects html_static_path and html_extra_path.
70 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', "../.git/.*", ".git/.*"]
71 
72 # The name of the Pygments (syntax highlighting) style to use.
73 pygments_style = None
74 
75 
76 # -- Options for HTML output -------------------------------------------------
77 html_extra_path = ['_doxy/html']
78 
79 # The theme to use for HTML and HTML Help pages. See the documentation for
80 # a list of builtin themes.
81 #
82 #html_theme = 'alabaster'
83 html_theme = 'sphinx_rtd_theme'
84 
85 # Theme options are theme-specific and customize the look and feel of a theme
86 # further. For a list of options available for each theme, see the
87 # documentation.
88 #
89 # html_theme_options = {}
90 
91 # Add any paths that contain custom static files (such as style sheets) here,
92 # relative to this directory. They are copied after the builtin static files,
93 # so a file named "default.css" will overwrite the builtin "default.css".
94 html_static_path = ['_static']
95 
96 # Custom sidebar templates, must be a dictionary that maps document names
97 # to template names.
98 #
99 # The default sidebars (for documents that don't match any pattern) are
100 # defined by theme itself. Builtin themes are using these templates by
101 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
102 # 'searchbox.html']``.
103 #
104 # html_sidebars = {}
105 
106 
107 # -- Options for HTMLHelp output ---------------------------------------------
108 
109 # Output file base name for HTML help builder.
110 htmlhelp_basename = 'DISPATCHdoc'
111 
112 
113 # -- Options for LaTeX output ------------------------------------------------
114 
115 latex_elements = {
116  # The paper size ('letterpaper' or 'a4paper').
117  #
118  # 'papersize': 'letterpaper',
119 
120  # The font size ('10pt', '11pt' or '12pt').
121  #
122  # 'pointsize': '10pt',
123 
124  # Additional stuff for the LaTeX preamble.
125  #
126  # 'preamble': '',
127 
128  # Latex figure (float) alignment
129  #
130  # 'figure_align': 'htbp',
131 }
132 
133 # Grouping the document tree into LaTeX files. List of tuples
134 # (source start file, target name, title,
135 # author, documentclass [howto, manual, or own class]).
136 latex_documents = [
137  (master_doc, 'DISPATCH.tex', 'DISPATCH Documentation',
138  u'Åke Nordlund', 'manual'),
139 ]
140 
141 
142 # -- Options for manual page output ------------------------------------------
143 
144 # One entry per manual page. List of tuples
145 # (source start file, name, description, authors, manual section).
146 man_pages = [
147  (master_doc, 'dispatch', 'DISPATCH Documentation',
148  [author], 1)
149 ]
150 
151 
152 # -- Options for Texinfo output ----------------------------------------------
153 
154 # Grouping the document tree into Texinfo files. List of tuples
155 # (source start file, target name, title, author,
156 # dir menu entry, description, category)
157 texinfo_documents = [
158  (master_doc, 'DISPATCH', 'DISPATCH Documentation',
159  author, 'DISPATCH', 'One line description of project.',
160  'Miscellaneous'),
161 ]
162 
163 
164 # -- Options for Epub output -------------------------------------------------
165 
166 # Bibliographic Dublin Core info.
167 epub_title = project
168 
169 # The unique identifier of the text. This can be a ISBN number
170 # or the project homepage.
171 #
172 # epub_identifier = ''
173 
174 # A unique identification for the text.
175 #
176 # epub_uid = ''
177 
178 # A list of files that should not be packed into the epub file.
179 epub_exclude_files = ['search.html']
180 
181 
182 # -- Extension configuration -------------------------------------------------
183 
184 # -- Options for todo extension ----------------------------------------------
185 
186 # If true, `todo` and `todoList` produce output, else they produce nothing.
187 todo_include_todos = True
188 
189 import subprocess
190 subprocess.call('doxygen', shell=True)
191 subprocess.call('ls -R', shell=True)
192 
193 
194 
195 
196 ###########################################################################
197 # auto-created readthedocs.org specific configuration #
198 ###########################################################################
199 
200 
201 #
202 # The following code was added during an automated build on readthedocs.org
203 # It is auto created and injected for every build. The result is based on the
204 # conf.py.tmpl file found in the readthedocs.org codebase:
205 # https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
206 #
207 
208 
209 import importlib
210 import sys
211 import os.path
212 from six import string_types
213 
214 from sphinx import version_info
215 
216 # Get suffix for proper linking to GitHub
217 # This is deprecated in Sphinx 1.3+,
218 # as each page can have its own suffix
219 if globals().get('source_suffix', False):
220  if isinstance(source_suffix, string_types):
221  SUFFIX = source_suffix
222  elif isinstance(source_suffix, (list, tuple)):
223  # Sphinx >= 1.3 supports list/tuple to define multiple suffixes
224  SUFFIX = source_suffix[0]
225  elif isinstance(source_suffix, dict):
226  # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
227  SUFFIX = list(source_suffix.keys())[0] # make a ``list()`` for py2/py3 compatibility
228  else:
229  # default to .rst
230  SUFFIX = '.rst'
231 else:
232  SUFFIX = '.rst'
233 
234 # Add RTD Static Path. Add to the end because it overwrites previous files.
235 if not 'html_static_path' in globals():
236  html_static_path = []
237 if os.path.exists('_static'):
238  html_static_path.append('_static')
239 
240 # Add RTD Theme only if they aren't overriding it already
241 using_rtd_theme = (
242  (
243  'html_theme' in globals() and
244  html_theme in ['default'] and
245  # Allow people to bail with a hack of having an html_style
246  'html_style' not in globals()
247  ) or 'html_theme' not in globals()
248 )
249 if using_rtd_theme:
250  theme = importlib.import_module('sphinx_rtd_theme')
251  html_theme = 'sphinx_rtd_theme'
252  html_style = None
253  html_theme_options = {}
254  if 'html_theme_path' in globals():
255  html_theme_path.append(theme.get_html_theme_path())
256  else:
257  html_theme_path = [theme.get_html_theme_path()]
258 
259 if globals().get('websupport2_base_url', False):
260  websupport2_base_url = 'https://readthedocs.org/websupport'
261  websupport2_static_url = 'https://assets.readthedocs.org/static/'
262 
263 
264 #Add project information to the template context.
265 context = {
266  'using_theme': using_rtd_theme,
267  'html_theme': html_theme,
268  'current_version': "latest",
269  'version_slug': "latest",
270  'MEDIA_URL': "https://media.readthedocs.org/",
271  'STATIC_URL': "https://assets.readthedocs.org/static/",
272  'PRODUCTION_DOMAIN': "readthedocs.org",
273  'versions': [
274  ("latest", "/en/latest/"),
275  ("stable", "/en/stable/"),
276  ],
277  'downloads': [
278  ("pdf", "//dispatch.readthedocs.io/_/downloads/en/latest/pdf/"),
279  ("html", "//dispatch.readthedocs.io/_/downloads/en/latest/htmlzip/"),
280  ("epub", "//dispatch.readthedocs.io/_/downloads/en/latest/epub/"),
281  ],
282  'subprojects': [
283  ],
284  'slug': 'dispatch',
285  'name': u'DISPATCH',
286  'rtd_language': u'en',
287  'programming_language': u'words',
288  'canonical_url': 'https://dispatch.readthedocs.io/en/latest/',
289  'analytics_code': 'UA-142581668-2',
290  'single_version': False,
291  'conf_py_path': '/docs/',
292  'api_host': 'https://readthedocs.org',
293  'proxied_api_host': 'https://readthedocs.org',
294  'github_user': 'None',
295  'github_repo': 'None',
296  'github_version': 'master',
297  'display_github': False,
298  'bitbucket_user': 'aanordlund',
299  'bitbucket_repo': 'dispatch',
300  'bitbucket_version': 'master',
301  'display_bitbucket': True,
302  'gitlab_user': 'None',
303  'gitlab_repo': 'None',
304  'gitlab_version': 'master',
305  'display_gitlab': False,
306  'READTHEDOCS': True,
307  'using_theme': (html_theme == "default"),
308  'new_theme': (html_theme == "sphinx_rtd_theme"),
309  'source_suffix': SUFFIX,
310  'ad_free': False,
311  'user_analytics_code': 'UA-142581668-2',
312  'global_analytics_code': 'UA-17997319-1',
313  'commit': 'f89d4f60',
314 }
315 
316 
317 
318 
319 if 'html_context' in globals():
320 
321  html_context.update(context)
322 
323 else:
324  html_context = context
325 
326 # Add custom RTD extension
327 if 'extensions' in globals():
328  # Insert at the beginning because it can interfere
329  # with other extensions.
330  # See https://github.com/rtfd/readthedocs.org/pull/4054
331  extensions.insert(0, "readthedocs_ext.readthedocs")
332 else:
333  extensions = ["readthedocs_ext.readthedocs"]
334 
335 # Add External version warning banner to the external version documentation
336 if 'branch' == 'external':
337  extensions.insert(1, "readthedocs_ext.external_version_warning")
338 
339 project_language = 'en'
340 
341 # User's Sphinx configurations
342 language_user = globals().get('language', None)
343 latex_engine_user = globals().get('latex_engine', None)
344 latex_elements_user = globals().get('latex_elements', None)
345 
346 # Remove this once xindy gets installed in Docker image and XINDYOPS
347 # env variable is supported
348 # https://github.com/rtfd/readthedocs-docker-images/pull/98
349 latex_use_xindy = False
350 
351 chinese = any([
352  language_user in ('zh_CN', 'zh_TW'),
353  project_language in ('zh_CN', 'zh_TW'),
354 ])
355 
356 japanese = any([
357  language_user == 'ja',
358  project_language == 'ja',
359 ])
360 
361 if chinese:
362  latex_engine = latex_engine_user or 'xelatex'
363 
364  latex_elements_rtd = {
365  'preamble': '\\usepackage[UTF8]{ctex}\n',
366  }
367  latex_elements = latex_elements_user or latex_elements_rtd
368 elif japanese:
369  latex_engine = latex_engine_user or 'platex'