Coverage for utilities/documentation.py: 6%

1""" 

2Documentation 

3============= 

4 

5Define objects and utilities for documentation generation and processing. 

6""" 

7 

8from __future__ import annotations 

9 

10import os 

11 

12__author__ = "Colour Developers" 

13__copyright__ = "Copyright 2013 Colour Developers" 

14__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause" 

15__maintainer__ = "Colour Developers" 

16__email__ = "colour-developers@colour-science.org" 

17__status__ = "Production" 

18 

19__all__ = [ 

20 "DocstringDict", 

21 "DocstringFloat", 

22 "DocstringInt", 

23 "DocstringText", 

24 "DocstringTuple", 

25 "is_documentation_building", 

26] 

27 

28 

29class DocstringDict(dict): 

30 """ 

31 Define a :class:`dict` sub-class that allows docstring attachment to 

32 :class:`dict` instances. 

33 """ 

34 

35 

36class DocstringFloat(float): 

37 """ 

38 Define a :class:`float` sub-class that allows docstring attachment to 

39 :class:`float` instances. 

40 """ 

41 

42 

43class DocstringInt(int): 

44 """ 

45 Define an :class:`int` sub-class that allows docstring attachment to 

46 :class:`int` instances. 

47 """ 

48 

49 

50class DocstringText(str): # noqa: SLOT000 

51 """ 

52 Define a :class:`str` sub-class that allows docstring attachment to 

53 :class:`str` instances. 

54 """ 

55 

56 

57class DocstringTuple(tuple): # noqa: SLOT001 

58 """ 

59 Define a :class:`tuple` sub-class that allows docstring attachment to 

60 :class:`tuple` instances. 

61 """ 

62 

63 

64def is_documentation_building() -> bool: 

65 """ 

66 Determine whether the documentation is being built by checking for the 

67 *READTHEDOCS* or *COLOUR_SCIENCE__DOCUMENTATION_BUILD* environment 

68 variables. 

69 

70 Returns 

71 ------- 

72 :class:`bool` 

73 Whether the documentation is being built. 

74 

75 Examples 

76 -------- 

77 >>> is_documentation_building() 

78 False 

79 >>> os.environ["READTHEDOCS"] = "True" 

80 >>> is_documentation_building() 

81 True 

82 >>> os.environ["READTHEDOCS"] = "False" 

83 >>> is_documentation_building() 

84 True 

85 >>> del os.environ["READTHEDOCS"] 

86 >>> is_documentation_building() 

87 False 

88 >>> os.environ["COLOUR_SCIENCE__DOCUMENTATION_BUILD"] = "Yes" 

89 >>> is_documentation_building() 

90 True 

91 >>> del os.environ["COLOUR_SCIENCE__DOCUMENTATION_BUILD"] 

92 """ 

93 

94 return bool( 

95 os.environ.get("READTHEDOCS") 

96 or os.environ.get("COLOUR_SCIENCE__DOCUMENTATION_BUILD") 

97 )