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 

13 

14 

15class CustomSphinxApp(Sphinx): 

16 """ 

17 A subclass of class *Sphinx*, 

18 the goal is to interpret :epkg:`RST` with custom directives. 

19 """ 

20 

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) 

52 

53 if confdir is None: 

54 confdir = srcdir 

55 else: 

56 confdir = os.path.abspath(confdir) 

57 

58 if doctreedir is None: 

59 doctreedir = os.path.join(outdir, '_pyq', 'doctrees') 

60 if not os.path.exists(doctreedir): 

61 os.makedirs(doctreedir) 

62 

63 if confoverrides is None: 

64 confoverrides = {} 

65 if status is None: 

66 status = StringIO() 

67 if warning is None: 

68 warning = StringIO() 

69 

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__ 

82 

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 

101 

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) 

110 

111 self._add_missing_element_in_config() 

112 

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 } 

123 

124 def __str__(self): 

125 """ 

126 usual 

127 """ 

128 classname = self.__class__.__name__ 

129 return '<%s buildername=%r>' % (classname, self.builder.name) 

130 

131 def cleanup(self, error=None): 

132 """ 

133 do some cleanup 

134 

135 @param error error is an exception 

136 """ 

137 from sphinx.theming import Theme 

138 

139 if error and self.cleanup_on_errors is False: 

140 return 

141 

142 Theme.themes.clear() 

143 for tree in self.cleanup_trees: 

144 shutil.rmtree(tree, True)