Coverage for utilities/documentation.py: 6%

1"""

2 Documentation

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

4

5 Define objects and utilities for documentation generation and processing.

6"""

7

8 from __future__ import annotations

9

10 import 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

29 class DocstringDict(dict):

30 """

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

32 :class:`dict` instances.

33 """

34

35

36 class DocstringFloat(float):

37 """

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

39 :class:`float` instances.

40 """

41

42

43 class DocstringInt(int):

44 """

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

46 :class:`int` instances.

47 """

48

49

50 class DocstringText(str): # noqa: SLOT000

51 """

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

53 :class:`str` instances.

54 """

55

56

57 class DocstringTuple(tuple): # noqa: SLOT001

58 """

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

60 :class:`tuple` instances.

61 """

62

63

64 def 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 )