Coverage for pycommons / dev / doc / index_rst.py: 100%

1""" 

2Make an `index.rst` file. 

3 

4In all of my projects, the `index.rst` files have the same contents, 

5basically. So here we generate them on the fly based on the documentation 

6information data. Since this data contains the index of the last section 

7in the `README.md` files, this allows me to properly number the code section. 

8""" 

9from typing import Any, Callable 

10 

11from pycommons.dev.doc.doc_info import DocInfo 

12from pycommons.io.console import logger 

13from pycommons.types import type_error 

14 

15 

16def make_index_rst(info: DocInfo, collector: Callable[[str], Any]) -> None: 

17 """ 

18 Create the `index.rst` file contents. 

19 

20 :param info: The documentation information 

21 :param collector: the collector to receive the information. 

22 

23 >>> di = DocInfo(__file__, "a", "b", "bla", "1.2", 12, 

24 ... "https://example.com") 

25 >>> from contextlib import redirect_stdout 

26 >>> l = [] 

27 >>> with redirect_stdout(None): 

28 ... make_index_rst(di, l.append) 

29 >>> for s in l: 

30 ... print(s) 

31 bla 

32 === 

33 <BLANKLINE> 

34 * :ref:`genindex` 

35 * :ref:`modindex` 

36 * :ref:`search` 

37 <BLANKLINE> 

38 .. include:: README.md 

39 :parser: myst_parser.sphinx_ 

40 <BLANKLINE> 

41 13. Modules and Code 

42 -------------------- 

43 <BLANKLINE> 

44 .. toctree:: 

45 :maxdepth: 4 

46 <BLANKLINE> 

47 modules 

48 

49 >>> try: 

50 ... make_index_rst(None, print) 

51 ... except TypeError as te: 

52 ... print(str(te)[:70]) 

53 info should be an instance of pycommons.dev.doc.doc_info.DocInfo but i 

54 

55 >>> try: 

56 ... make_index_rst(1, print) 

57 ... except TypeError as te: 

58 ... print(str(te)[:70]) 

59 info should be an instance of pycommons.dev.doc.doc_info.DocInfo but i 

60 

61 >>> try: 

62 ... make_index_rst(di, None) 

63 ... except TypeError as te: 

64 ... print(str(te)) 

65 collector should be a callable but is None. 

66 

67 >>> try: 

68 ... make_index_rst(di, 1) 

69 ... except TypeError as te: 

70 ... print(str(te)) 

71 collector should be a callable but is int, namely 1. 

72 """ 

73 if not isinstance(info, DocInfo): 

74 raise type_error(info, "info", DocInfo) 

75 if not callable(collector): 

76 raise type_error(collector, "collector", call=True) 

77 logger(f"Now creating index.rst contents for project {info.project!r}.") 

78 

79 collector(info.title) 

80 collector("=" * str.__len__(info.title)) 

81 collector("") 

82 collector("* :ref:`genindex`") 

83 collector("* :ref:`modindex`") 

84 collector("* :ref:`search`") 

85 collector("") 

86 collector(".. include:: README.md") 

87 collector(" :parser: myst_parser.sphinx_") 

88 collector("") 

89 mac: str = "Modules and Code" 

90 if info.last_major_section_index is not None: 

91 mac = f"{info.last_major_section_index + 1}. {mac}" 

92 collector(mac) 

93 collector("-" * str.__len__(mac)) 

94 collector("") 

95 collector(".. toctree::") 

96 collector(" :maxdepth: 4") 

97 collector("") 

98 collector(" modules") 

99 logger("Finished creating index.rst contents for " 

100 f"project {info.project!r}.")