Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2"""
3@file
4@brief Inspired from module
5`sphinx-testing <https://github.com/sphinx-doc/sphinx-testing/>`_
6"""
7import shutil
8import os
9import warnings
10from io import StringIO
11from sphinx.application import Sphinx
12from .default_conf import latex_preamble
15class CustomSphinxApp(Sphinx):
16 """
17 A subclass of class *Sphinx*,
18 the goal is to interpret :epkg:`RST` with custom directives.
19 """
21 def __init__(self, srcdir, outdir, confdir=None, doctreedir=None,
22 buildername='html', confoverrides=None, status=None,
23 warning=None, freshenv=False, warningiserror=False, tags=None,
24 copy_srcdir_to_tmpdir=False, create_new_srcdir=False,
25 cleanup_on_errors=True, verbosity=0, parallel=0,
26 extensions='all'):
27 """
28 @param srcdir source folder
29 @param outdir output folder
30 @param confdir configuration folder, default is srcdir
31 @param doctreedir doc tree folder
32 @param buildername HTML by default
33 @param confoverrides None or dictionary
34 @param status StringIO to retrieve them
35 @param warning StringIO to retrieve them
36 @param freshenv boolean
37 @param warningiserror warning as errors?
38 @param tags additional documentation
39 @param copy_srcdir_to_tmpdir copy the source to a temporary directory
40 @param create_new_srcdir create a new source directory
41 @param cleanup_on_errors force cleanup on errors
42 @param verbosity integer
43 @param parallel integer (number of threads)
44 @param extensions if ``'all'``, add extensions implemented
45 by this module, use ``None`` for an empty list,
46 'extensions' must not be in *confoverrides*
47 """
48 self.cleanup_trees = []
49 self.cleanup_on_errors = cleanup_on_errors
50 srcdir = os.path.abspath(srcdir)
51 outdir = os.path.abspath(outdir)
53 if confdir is None:
54 confdir = srcdir
55 else:
56 confdir = os.path.abspath(confdir)
58 if doctreedir is None:
59 doctreedir = os.path.join(outdir, '_pyq', 'doctrees')
60 if not os.path.exists(doctreedir):
61 os.makedirs(doctreedir)
63 if confoverrides is None:
64 confoverrides = {}
65 if status is None:
66 status = StringIO()
67 if warning is None:
68 warning = StringIO()
70 if buildername == "rst":
71 from ..sphinxext.sphinx_rst_builder import RstBuilder
72 module = RstBuilder.__module__
73 elif buildername == "md":
74 from ..sphinxext.sphinx_md_builder import MdBuilder
75 module = MdBuilder.__module__
76 elif buildername in ("latex", "elatex", "pdf"):
77 from ..sphinxext.sphinx_latex_builder import EnhancedLaTeXBuilder
78 module = EnhancedLaTeXBuilder.__module__
79 elif buildername == "doctree":
80 from ..sphinxext.sphinx_doctree_builder import DocTreeBuilder
81 module = DocTreeBuilder.__module__
83 if 'extensions' not in confoverrides:
84 if extensions == 'all':
85 from ..sphinxext import get_default_extensions, get_default_standard_extensions
86 exts = get_default_extensions(load_bokeh=False)
87 exts += get_default_standard_extensions()
88 skip = {'sphinx.ext.extlinks'}
89 exts = [_ for _ in exts if _ not in skip]
90 if buildername == "rst":
91 exts.insert(0, module)
92 elif isinstance(extensions, list):
93 exts = extensions
94 if buildername == "rst":
95 exts = exts.copy()
96 exts.insert(0, module)
97 elif buildername in ("rst", "md"):
98 exts = [module]
99 if exts is not None:
100 confoverrides['extensions'] = exts
102 # delayed import to speed up time
103 with warnings.catch_warnings():
104 warnings.simplefilter(
105 "ignore", (DeprecationWarning, PendingDeprecationWarning))
106 Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir,
107 buildername, confoverrides, status,
108 warning, freshenv, warningiserror, tags,
109 verbosity, parallel)
111 self._add_missing_element_in_config()
113 def _add_missing_element_in_config(self):
114 """
115 Adds extra elements in config such as ``latex_elements``.
116 """
117 if not hasattr(self.config, "latex_elements"):
118 self.config.latex_elements = {
119 'papersize': 'a4',
120 'pointsize': '10pt',
121 'preamble': latex_preamble(),
122 }
124 def __str__(self):
125 """
126 usual
127 """
128 classname = self.__class__.__name__
129 return '<%s buildername=%r>' % (classname, self.builder.name)
131 def cleanup(self, error=None):
132 """
133 do some cleanup
135 @param error error is an exception
136 """
137 from sphinx.theming import Theme
139 if error and self.cleanup_on_errors is False:
140 return
142 Theme.themes.clear()
143 for tree in self.cleanup_trees:
144 shutil.rmtree(tree, True)