Coverage for pyquickhelper/sphinxext/sphinxext_helper.py: 88%
32 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"""
2@file
3@brief Helpers for sphinx extensions.
4"""
5import os
8def try_add_config_value(app, name, default, rebuild, type_s=()):
9 """
10 Add a variables in the config file if it does not have it yet.
12 @param app Sphinx application
13 @param name name of the variable
14 @param default default value
15 @param rebuild see below
16 @param type_s expected types
17 @return True if added, False if already present.
19 Rebuilds can be (source: `Sphinx.add_config_value
20 <https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_config_value>`_):
22 * 'env' if a change in the setting only takes effect when a document
23 is parsed - this means that the whole environment must be rebuilt.
24 * 'html' if a change in the setting needs a full rebuild of HTML documents.
25 * '' if a change in the setting will not need any special rebuild.
27 """
28 if name in app.config:
29 return False
30 app.add_config_value(name, default, rebuild, type_s)
31 return True
34def get_env_state_info(self):
35 """
36 Retrieves an environment and a docname inside a directive.
38 @param self self inside a :epkg:`Sphinx` directive
39 @return env, docname, lineno
40 """
41 if hasattr(self, 'env') and self.env is not None:
42 env = self.env
43 elif hasattr(self.state.document.settings, "env"):
44 env = self.state.document.settings.env
45 else:
46 env = None # pragma: no cover
48 reporter = self.state.document.reporter
49 try:
50 docname, lineno = reporter.get_source_and_line(self.lineno)
51 except AttributeError: # pragma: no cover
52 docname = lineno = None
54 if docname is not None:
55 docname = docname.replace("\\", "/").split("/")[-1]
56 res = {'env': env, 'reporter_docname': docname,
57 'docname': env.docname,
58 'lineno': lineno, 'state_document': self.state.document,
59 'location': self.state_machine.get_source_and_line(self.lineno)}
60 if hasattr(self, 'app'):
61 res['srcdic'] = self.app.builder.srcdir
62 if hasattr(self, 'builder'):
63 res['srcdic'] = self.builder.srcdir
64 if env is not None:
65 here = os.path.dirname(env.doc2path("HERE"))
66 if "IMPOSSIBLE:TOFIND" not in here:
67 res['HERE'] = here
69 keys = list(res.keys())
70 for k in keys: # pylint: disable=C0206
71 if isinstance(res[k], str):
72 res[k] = res[k].replace("\\", "/")
73 elif isinstance(res[k], tuple):
74 res[k] = (res[k][0].replace("\\", "/"), res[k][1])
75 return res