Coverage for src / mafw / devtools / documentation / __init__.py: 100%

1# Copyright 2025–2026 European Union 

2# Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu) 

3# SPDX-License-Identifier: EUPL-1.2 

4""" 

5Documentation management utilities for MAFw development tools. 

6 

7This package provides business logic for building versioned documentation, 

8managing versions.json, generating redirect pages, creating requirements 

9documentation, and running local documentation servers. 

10""" 

11 

12from mafw.devtools import ensure_devtools_available 

13 

14ensure_devtools_available() 

15 

16from mafw.devtools.documentation.builder import ( # noqa: E402 

17 DEFAULT_MIN_TAG_REGEX, 

18 DOCS_SUBPATH, 

19 OLD_VERSION_TO_BE_PATCHED, 

20 SPHINX_BUILD_CMD, 

21 build_for_tag, 

22 build_pdf_for_tag, 

23 check_multiversion_structure, 

24 copy_patch_files, 

25 create_docs_zip_for_tag, 

26 ensure_sphinx_build_available, 

27 extract_docs_zip_to_repo_root, 

28 filter_latest_micro, 

29 filter_stable_tags, 

30 filter_versions_in_range, 

31 find_repo_root, 

32 generate_pdf_index_page, 

33 iter_local_mafw_docs_zips, 

34 normalize_registry_item, 

35 parse_mafw_docs_zip_filename, 

36 parse_sphinx_log, 

37 parse_version_tuple, 

38 report_build_status, 

39 run, 

40) 

41from mafw.devtools.documentation.requirements import ( # noqa: E402 

42 PYTHON_VERSIONS_REQUIREMENTS_FILENAME, 

43 REQUIREMENTS_GROUPS, 

44 _load_supported_python_versions, 

45 generate_python_versions_rst, 

46 generate_requirements_rst, 

47) 

48from mafw.devtools.documentation.server import ( # noqa: E402 

49 SERVER_DEFAULT_DIRECTORY, 

50 SERVER_METADATA_FILENAME, 

51 ServerStatusEnum, 

52 format_started_at_utc, 

53 http_probe, 

54 process_matches_http_server, 

55 read_server_metadata, 

56 server_default_directory, 

57 server_metadata_path, 

58 write_server_metadata, 

59) 

60from mafw.devtools.documentation.versions import ( # noqa: E402 

61 ensure_versions_json_exists, 

62 format_size, 

63 get_directory_size, 

64 mirror_version, 

65 prune_old_versions, 

66 regenerate_versions_json_after_pruning, 

67 write_legacy_redirect_page, 

68 write_redirect_page, 

69 write_redirects_file, 

70 write_root_landing_page, 

71 write_versions_json, 

72) 

73from mafw.devtools.git import ( # noqa: E402 

74 get_current_branch, 

75 get_git_tags, 

76 git_rev_of, 

77 is_ancestor, 

78 sort_tags_semver, 

79) 

80from mafw.devtools.gitlab import ( # noqa: E402 

81 build_gitlab_api_configuration, 

82 build_gitlab_auth_headers, 

83) 

84from mafw.devtools.gitlab.docs_registry import ( # noqa: E402 

85 download_docs_zip_from_gitlab_generic_registry, 

86 list_mafw_docs_generic_packages, 

87 resolve_mafw_docs_package_ids_by_version, 

88 upload_docs_zip_to_gitlab_generic_registry, 

89) 

90 

91__all__ = [ 

92 'DEFAULT_MIN_TAG_REGEX', 

93 'DOCS_SUBPATH', 

94 'OLD_VERSION_TO_BE_PATCHED', 

95 'PYTHON_VERSIONS_REQUIREMENTS_FILENAME', 

96 'REQUIREMENTS_GROUPS', 

97 'SERVER_DEFAULT_DIRECTORY', 

98 'SERVER_METADATA_FILENAME', 

99 'SPHINX_BUILD_CMD', 

100 'ServerStatusEnum', 

101 '_load_supported_python_versions', 

102 'format_started_at_utc', 

103 'http_probe', 

104 'process_matches_http_server', 

105 'read_server_metadata', 

106 'server_default_directory', 

107 'server_metadata_path', 

108 'write_server_metadata', 

109 'build_for_tag', 

110 'build_gitlab_api_configuration', 

111 'build_gitlab_auth_headers', 

112 'build_pdf_for_tag', 

113 'check_multiversion_structure', 

114 'copy_patch_files', 

115 'create_docs_zip_for_tag', 

116 'download_docs_zip_from_gitlab_generic_registry', 

117 'ensure_sphinx_build_available', 

118 'ensure_versions_json_exists', 

119 'extract_docs_zip_to_repo_root', 

120 'filter_latest_micro', 

121 'filter_stable_tags', 

122 'filter_versions_in_range', 

123 'find_repo_root', 

124 'format_size', 

125 'generate_pdf_index_page', 

126 'generate_python_versions_rst', 

127 'generate_requirements_rst', 

128 'get_current_branch', 

129 'get_directory_size', 

130 'get_git_tags', 

131 'git_rev_of', 

132 'is_ancestor', 

133 'iter_local_mafw_docs_zips', 

134 'list_mafw_docs_generic_packages', 

135 'mirror_version', 

136 'normalize_registry_item', 

137 'parse_mafw_docs_zip_filename', 

138 'parse_sphinx_log', 

139 'parse_version_tuple', 

140 'prune_old_versions', 

141 'regenerate_versions_json_after_pruning', 

142 'report_build_status', 

143 'resolve_mafw_docs_package_ids_by_version', 

144 'run', 

145 'sort_tags_semver', 

146 'upload_docs_zip_to_gitlab_generic_registry', 

147 'write_legacy_redirect_page', 

148 'write_redirect_page', 

149 'write_redirects_file', 

150 'write_root_landing_page', 

151 'write_versions_json', 

152] 

153 

154# Set canonical module for Sphinx cross-references 

155for _obj in ( 

156 ServerStatusEnum, 

157 format_started_at_utc, 

158 http_probe, 

159 process_matches_http_server, 

160 read_server_metadata, 

161 server_default_directory, 

162 server_metadata_path, 

163 write_server_metadata, 

164 _load_supported_python_versions, 

165 build_for_tag, 

166 build_gitlab_api_configuration, 

167 build_gitlab_auth_headers, 

168 build_pdf_for_tag, 

169 check_multiversion_structure, 

170 copy_patch_files, 

171 create_docs_zip_for_tag, 

172 download_docs_zip_from_gitlab_generic_registry, 

173 ensure_sphinx_build_available, 

174 ensure_versions_json_exists, 

175 extract_docs_zip_to_repo_root, 

176 filter_latest_micro, 

177 filter_stable_tags, 

178 filter_versions_in_range, 

179 find_repo_root, 

180 format_size, 

181 generate_pdf_index_page, 

182 generate_python_versions_rst, 

183 generate_requirements_rst, 

184 get_current_branch, 

185 get_directory_size, 

186 get_git_tags, 

187 git_rev_of, 

188 is_ancestor, 

189 iter_local_mafw_docs_zips, 

190 list_mafw_docs_generic_packages, 

191 mirror_version, 

192 normalize_registry_item, 

193 parse_mafw_docs_zip_filename, 

194 parse_sphinx_log, 

195 parse_version_tuple, 

196 prune_old_versions, 

197 regenerate_versions_json_after_pruning, 

198 report_build_status, 

199 resolve_mafw_docs_package_ids_by_version, 

200 run, 

201 sort_tags_semver, 

202 upload_docs_zip_to_gitlab_generic_registry, 

203 write_legacy_redirect_page, 

204 write_redirect_page, 

205 write_redirects_file, 

206 write_root_landing_page, 

207 write_versions_json, 

208): 

209 _obj.__module__ = __name__ 

210del _obj