Coverage for pyquickhelper/helpgen/sphinxm_custom_app.py: 71%

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 ( 

86 get_default_extensions, 

87 get_default_standard_extensions) 

88 exts = get_default_extensions() 

89 exts += get_default_standard_extensions() 

90 skip = {'sphinx.ext.extlinks'} 

91 exts = [_ for _ in exts if _ not in skip] 

92 if buildername == "rst": 

93 exts.insert(0, module) 

94 elif isinstance(extensions, list): 

95 exts = extensions 

96 if buildername == "rst": 

97 exts = exts.copy() 

98 exts.insert(0, module) 

99 elif buildername in ("rst", "md"): 

100 exts = [module] 

101 if exts is not None: 

102 confoverrides['extensions'] = exts 

103 

104 # delayed import to speed up time 

105 with warnings.catch_warnings(): 

106 warnings.simplefilter( 

107 "ignore", (DeprecationWarning, PendingDeprecationWarning)) 

108 Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir, 

109 buildername, confoverrides, status, 

110 warning, freshenv, warningiserror, tags, 

111 verbosity, parallel) 

112 

113 self._add_missing_element_in_config() 

114 

115 def _add_missing_element_in_config(self): 

116 """ 

117 Adds extra elements in config such as ``latex_elements``. 

118 """ 

119 if not hasattr(self.config, "latex_elements"): 

120 self.config.latex_elements = { 

121 'papersize': 'a4', 

122 'pointsize': '10pt', 

123 'preamble': latex_preamble(), 

124 } 

125 

126 def __str__(self): 

127 """ 

128 usual 

129 """ 

130 classname = self.__class__.__name__ 

131 return f'<{classname} buildername={self.builder.name!r}>' 

132 

133 def cleanup(self, error=None): 

134 """ 

135 do some cleanup 

136 

137 @param error error is an exception 

138 """ 

139 from sphinx.theming import Theme 

140 

141 if error and self.cleanup_on_errors is False: 

142 return 

143 

144 Theme.themes.clear() 

145 for tree in self.cleanup_trees: 

146 shutil.rmtree(tree, True)