Generate an include file. - directory - subdirectory to put file in - basename - base name of the file - contents - contents of the file (Asciidoc boilerplate aside)
(self, directory, basename, contents, deprecatedby, deprecatedlink, supersededby)
| 268 | return deprecators |
| 269 | |
| 270 | def writeInclude(self, directory, basename, contents, deprecatedby, deprecatedlink, supersededby): |
| 271 | """Generate an include file. |
| 272 | |
| 273 | - directory - subdirectory to put file in |
| 274 | - basename - base name of the file |
| 275 | - contents - contents of the file (Asciidoc boilerplate aside)""" |
| 276 | # Create subdirectory, if needed |
| 277 | directory = Path(self.genOpts.directory) / directory |
| 278 | self.makeDir(directory) |
| 279 | |
| 280 | # Create file |
| 281 | filename = directory / (f"{basename}{self.file_suffix}") |
| 282 | self.logMsg('diag', '# Generating include file:', str(filename)) |
| 283 | fp = open(filename, 'w', encoding='utf-8') |
| 284 | |
| 285 | # Asciidoc anchor |
| 286 | write(self.genOpts.conventions.warning_comment, file=fp) |
| 287 | write(f'[[{basename}]]', file=fp) |
| 288 | |
| 289 | if self.genOpts.conventions.generate_index_terms: |
| 290 | if basename.startswith(self.conventions.command_prefix): |
| 291 | index_term = f"{basename} (function)" |
| 292 | elif basename.startswith(self.conventions.type_prefix): |
| 293 | index_term = f"{basename} (type)" |
| 294 | elif basename.startswith(self.conventions.api_prefix): |
| 295 | index_term = f"{basename} (define)" |
| 296 | else: |
| 297 | index_term = basename |
| 298 | write(f'indexterm:[{index_term}]', file=fp) |
| 299 | |
| 300 | source_options = self.conventions.docgen_source_options |
| 301 | source_language = self.conventions.docgen_language |
| 302 | source_directive = f'[source{source_options},{source_language}]' |
| 303 | |
| 304 | # Output any deprecation warnings needed |
| 305 | if deprecatedby: |
| 306 | |
| 307 | deprecators = None |
| 308 | |
| 309 | # Use the supersededby attribute if present |
| 310 | if supersededby: |
| 311 | deprecators = '<<' + supersededby + ',' + supersededby + '>>' |
| 312 | # Otherwise, format the list of deprecating versions/extensions |
| 313 | else: |
| 314 | # Format the list of deprecators |
| 315 | deprecatedby_formatted = [] |
| 316 | for feature in deprecatedby: |
| 317 | deprecatedby_formatted.append(conventions.formatVersionOrExtension(feature)) |
| 318 | |
| 319 | # Join the list of deprecators so they make sense in prose |
| 320 | deprecators = deprecatedby_formatted[0] |
| 321 | if len(deprecatedby_formatted) == 2: |
| 322 | deprecators = deprecatedby_formatted[0] + " and " + deprecatedby_formatted[1] |
| 323 | elif len(deprecatedby_formatted) > 2: |
| 324 | deprecators = ", ".join(deprecatedby_formatted[:-1]) + ", and " + deprecatedby_formatted[-1] |
| 325 | |
| 326 | write("WARNING: This functionality is superseded by " + deprecators + ". See <<" + deprecatedlink + ", Legacy Functionality>> for more information.", file=fp); |
| 327 | write('', file=fp); |