def append_changelog_changes_ansible( builder: RstBuilder, changelog_entry: ChangelogEntry) -> PluginDataT: changelog = changelog_entry.ansible_changelog release_entries = changelog.generator.collect( squash=True, after_version=str(changelog_entry.prev_version) if changelog_entry.prev_version else None, until_version=changelog_entry.version_str) if not release_entries: return [] release_entry = release_entries[0] release_summary = release_entry.changes.pop('release_summary', None) if release_summary: builder.add_section('Release Summary', 1) builder.add_raw_rst(t.cast(str, release_summary)) builder.add_raw_rst('') if release_entry.empty: return [] return [("", "", changelog.generator, release_entry)]
def append_removed_collections(builder: RstBuilder, changelog_entry: ChangelogEntry) -> None: if changelog_entry.removed_collections: builder.add_section('Removed Collections', 1) for collector, collection_version in changelog_entry.removed_collections: builder.add_list_item(f"{collector.collection} " f"(previously included version: {collection_version})") builder.add_raw_rst('')
def append_unchanged_collections(builder: RstBuilder, changelog_entry: ChangelogEntry) -> None: if changelog_entry.unchanged_collections: builder.add_section('Unchanged Collections', 1) for collector, collection_version in changelog_entry.unchanged_collections: builder.add_list_item( f"{collector.collection} (still version {collection_version})") builder.add_raw_rst('')
def append_changelog_changes_collections(builder: RstBuilder, collection_metadata: CollectionsMetadata, changelog_entry: ChangelogEntry, is_last: bool) -> PluginDataT: result: PluginDataT = [] if changelog_entry.changed_collections: builder.add_section('Included Collections' if is_last else 'Changed Collections', 1) builder.add_raw_rst( 'If not mentioned explicitly, the changes are reported in the combined changelog' ' below.\n') headings = [ 'Collection', f'Ansible {changelog_entry.prev_version}', f'Ansible {changelog_entry.version_str}', 'Notes' ] cells = [] for ( collector, collection_version, prev_collection_version ) in changelog_entry.changed_collections: row = [collector.collection, '', str(collection_version), ''] if prev_collection_version is not None: row[1] = str(prev_collection_version) changelog = collector.changelog if changelog: release_entries = changelog.generator.collect( squash=True, after_version=prev_collection_version, until_version=collection_version) if not release_entries: row[-1] = "The collection did not have a changelog in this version." elif release_entries[0].empty: row[-1] = "There are no changes recorded in the changelog." else: result.append(( collector.collection, f"{collector.collection}.", changelog.generator, optimize_release_entry(release_entries[0]))) else: metadata = collection_metadata.get_meta(collector.collection) if metadata.changelog_url is not None: row[-1] = ( "You can find the collection's changelog at" f" `{metadata.changelog_url} <{metadata.changelog_url}>`_." ) else: row[-1] = ( "Unfortunately, this collection does not provide changelog data in a" " format that can be processed by the changelog generator." ) cells.append(row) render_rst_table(builder, headings, cells) builder.add_raw_rst('') return result
def append_changelog_changes_collections(builder: RstBuilder, collection_metadata: CollectionsMetadata, changelog_entry: ChangelogEntry, is_last: bool) -> PluginDataT: result: PluginDataT = [] if changelog_entry.changed_collections: builder.add_section('Included Collections' if is_last else 'Changed Collections', 1) for ( collector, collection_version, prev_collection_version ) in changelog_entry.changed_collections: if is_last: msg = f"{collector.collection} with version {collection_version}." if prev_collection_version is not None: msg += f" This was upgraded from version {prev_collection_version}." else: if prev_collection_version is None: msg = f"{collector.collection} was upgraded to version {collection_version}." else: msg = f"{collector.collection} was upgraded from" msg += f" version {prev_collection_version} to version {collection_version}." msg += "\n" changelog = collector.changelog if changelog: release_entries = changelog.generator.collect( squash=True, after_version=prev_collection_version, until_version=collection_version) if not release_entries: msg += "The collection did not have a changelog in this version." elif release_entries[0].empty: msg += "There are no changes recorded in the changelog." else: result.append(( collector.collection, f"{collector.collection}.", changelog.generator, release_entries[0])) msg += "The changes are reported in the combined changelog below." else: metadata = collection_metadata.get_meta(collector.collection) if metadata.changelog_url is not None: msg += "You can find the collection's changelog at" msg += f" `{metadata.changelog_url} <{metadata.changelog_url}>`_." else: msg += "Unfortunately, this collection does not provide changelog data in a" msg += " format that can be processed by the changelog generator." builder.add_list_item(msg) builder.add_raw_rst('') return result
def dump_plugins(builder: RstBuilder, plugins: PluginDumpT) -> None: last_title = [] for title, name, description in sorted(plugins): if title != last_title: if last_title: builder.add_raw_rst('') for i in range(common_start(last_title, title), len(title)): builder.add_section(title[i], i + 1) last_title = title builder.add_list_item(f"{name} - {description}") if last_title: builder.add_raw_rst('')
def append_changelog(builder: RstBuilder, collection_metadata: CollectionsMetadata, changelog_entry: ChangelogEntry, is_last: bool) -> None: builder.add_section('v{0}'.format(changelog_entry.version_str), 0) builder.add_raw_rst('.. contents::') builder.add_raw_rst(' :local:') builder.add_raw_rst(' :depth: 2\n') # Add release summary for Ansible data = append_changelog_changes_ansible(builder, changelog_entry) append_removed_collections(builder, changelog_entry) append_added_collections(builder, changelog_entry) # Adds Ansible-base section data.extend(append_changelog_changes_base(builder, changelog_entry)) builder.add_raw_rst('') # Adds list of changed collections data.extend( append_changelog_changes_collections(builder, collection_metadata, changelog_entry, is_last=is_last)) # Adds all changes for section, section_title in DEFAULT_SECTIONS: maybe_add_section_title = create_title_adder(builder, section_title, 1) for name, dummy, dummy, release_entry in data: if not release_entry or release_entry.has_no_changes([section]): continue next(maybe_add_section_title) if name: builder.add_section(name, 2) release_entry.add_section_content(builder, section) builder.add_raw_rst('') # Adds new plugins and modules add_plugins(builder, data) add_modules(builder, data) add_objects(builder, data) # Adds list of unchanged collections append_unchanged_collections(builder, changelog_entry)
def append_changelog_changes_base( builder: RstBuilder, changelog_entry: ChangelogEntry) -> PluginDataT: base_name = 'Ansible-base' if (changelog_entry.base_collector.latest.major > 2 or changelog_entry.base_collector.latest.minor > 10): base_name = 'Ansible-core' builder.add_section(base_name, 1) builder.add_raw_rst( f"Ansible {changelog_entry.version} contains {base_name} " f"version {changelog_entry.ansible_base_version}.") if changelog_entry.prev_ansible_base_version: if changelog_entry.prev_ansible_base_version == changelog_entry.ansible_base_version: builder.add_raw_rst( f"This is the same version of {base_name} as in " "the previous Ansible release.\n") return [] builder.add_raw_rst( f"This is a newer version than version " f"{changelog_entry.prev_ansible_base_version} contained in the " f"previous Ansible release.\n") changelog = changelog_entry.base_collector.changelog if not changelog: return [] release_entries = changelog.generator.collect( squash=True, after_version=changelog_entry.prev_ansible_base_version, until_version=changelog_entry.ansible_base_version) if not release_entries: builder.add_raw_rst( f"{base_name} did not have a changelog in this version.") return [] release_entry = release_entries[0] if release_entry.empty: builder.add_raw_rst("There are no changes recorded in the changelog.") return [] builder.add_raw_rst( "The changes are reported in the combined changelog below.") return [(base_name, "ansible.builtin.", changelog.generator, release_entry) ]
def append_porting_guide(builder: RstBuilder, changelog_entry: ChangelogEntry) -> None: maybe_add_title = create_title_adder( builder, 'Porting Guide for v{0}'.format(changelog_entry.version_str), 0) for section in ['known_issues', 'breaking_changes', 'major_changes']: append_porting_guide_section(builder, changelog_entry, maybe_add_title, section) if changelog_entry.removed_collections: next(maybe_add_title) builder.add_section('Removed Collections', 1) for collector, collection_version in changelog_entry.removed_collections: builder.add_list_item(f"{collector.collection} " f"(previously included version: {collection_version})") builder.add_raw_rst('') for section in ['removed_features', 'deprecated_features']: append_porting_guide_section(builder, changelog_entry, maybe_add_title, section)
def create_title_adder(builder: RstBuilder, title: str, level: int) -> t.Generator[None, None, None]: builder.add_section(title, level) while True: yield