Coverage for pyquickhelper/helpgen/sphinxm_custom_app.py: 71%
73 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-03 02:21 +0200
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 (
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
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)
113 self._add_missing_element_in_config()
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 }
126 def __str__(self):
127 """
128 usual
129 """
130 classname = self.__class__.__name__
131 return f'<{classname} buildername={self.builder.name!r}>'
133 def cleanup(self, error=None):
134 """
135 do some cleanup
137 @param error error is an exception
138 """
139 from sphinx.theming import Theme
141 if error and self.cleanup_on_errors is False:
142 return
144 Theme.themes.clear()
145 for tree in self.cleanup_trees:
146 shutil.rmtree(tree, True)