Coverage for pyquickhelper/sphinxext/sphinxext_helper.py: 88%

1""" 

2@file 

3@brief Helpers for sphinx extensions. 

4""" 

5import os 

6 

7 

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. 

11 

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. 

18 

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>`_): 

21 

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. 

26 

27 """ 

28 if name in app.config: 

29 return False 

30 app.add_config_value(name, default, rebuild, type_s) 

31 return True 

32 

33 

34def get_env_state_info(self): 

35 """ 

36 Retrieves an environment and a docname inside a directive. 

37 

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 

47 

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 

53 

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 

68 

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