From e455e4f1fef1d7caf7bf4a8fc2d5885c752c3748 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 15 Oct 2024 20:07:16 +0200 Subject: [PATCH] Update docs build to support the new antsibull-docs 2.15.0 features (#2001) * Provide information for antsibull-docs 2.15.0. * I don't think 'named' will ever get implemented. * The paths might be relative to the old CWD. * Show which commands are run. --- .../command_plugins/docs_build.py | 78 ++++++++++++------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/hacking/build_library/build_ansible/command_plugins/docs_build.py b/hacking/build_library/build_ansible/command_plugins/docs_build.py index e064bfddda..d0843b9117 100644 --- a/hacking/build_library/build_ansible/command_plugins/docs_build.py +++ b/hacking/build_library/build_ansible/command_plugins/docs_build.py @@ -39,7 +39,7 @@ class NoSuchFile(Exception): # Helpers # -def find_latest_ansible_dir(build_data_working): +def find_latest_ansible_dir(build_data_working) -> tuple[str, "packaging.version.Version"]: """Find the most recent ansible major version.""" # imports here so that they don't cause unnecessary deps for all of the plugins from packaging.version import InvalidVersion, Version @@ -47,7 +47,7 @@ def find_latest_ansible_dir(build_data_working): ansible_directories = glob.glob(os.path.join(build_data_working, '[0-9.]*')) # Find the latest ansible version directory - latest = None + latest_dir = None latest_ver = Version('0') for directory_name in (d for d in ansible_directories if os.path.isdir(d)): try: @@ -61,12 +61,12 @@ def find_latest_ansible_dir(build_data_working): if new_version > latest_ver: latest_ver = new_version - latest = directory_name + latest_dir = directory_name - if latest is None: + if latest_dir is None: raise NoSuchFile('Could not find an ansible data directory in {0}'.format(build_data_working)) - return latest + return latest_dir, latest_ver def parse_deps_file(filename): @@ -84,7 +84,7 @@ def write_deps_file(filename, deps_data): f.write(f'{key}: {value}\n') -def find_latest_deps_file(build_data_working, ansible_version): +def find_latest_deps_file(build_data_working, ansible_version: str) -> tuple[str, "packaging.version.Version"]: """Find the most recent ansible deps file for the given ansible major version.""" # imports here so that they don't cause unnecessary deps for all of the plugins from packaging.version import Version @@ -95,19 +95,19 @@ def find_latest_deps_file(build_data_working, ansible_version): raise Exception('No deps files exist for version {0}'.format(ansible_version)) # Find the latest version of the deps file for this major version - latest = None + latest_deps_file = None latest_ver = Version('0') for filename in deps_files: deps_data = parse_deps_file(filename) new_version = Version(deps_data['_ansible_version']) if new_version > latest_ver: latest_ver = new_version - latest = filename + latest_deps_file = filename - if latest is None: + if latest_deps_file is None: raise NoSuchFile('Could not find an ansible deps file in {0}'.format(data_dir)) - return latest + return latest_deps_file, latest_ver # @@ -133,9 +133,18 @@ def generate_core_docs(args): f.write(yaml.dump(deps_file_contents)) # Generate the plugin rst - return antsibull_docs.run(['antsibull-docs', 'stable', '--deps-file', modified_deps_file, - '--ansible-core-source', str(args.top_dir), - '--dest-dir', args.output_dir]) + full_command = [ + 'antsibull-docs', + 'stable', + '--deps-file', + modified_deps_file, + '--ansible-core-source', + str(args.top_dir), + '--dest-dir', + args.output_dir, + ] + print(f"Running {full_command!r}:") + return antsibull_docs.run(full_command) # If we make this more than just a driver for antsibull: # Run other rst generation @@ -164,16 +173,21 @@ def generate_full_docs(args): if args.ansible_build_data: build_data_working = args.ansible_build_data - ansible_version = args.ansible_version + ansible_version: str = args.ansible_version if ansible_version is None: - ansible_version = find_latest_ansible_dir(build_data_working) - params = ['devel', '--pieces-file', os.path.join(ansible_version, 'ansible.in')] + devel_dir, devel_version = find_latest_ansible_dir(build_data_working) + params = ['devel', '--pieces-file', 'ansible.in', '--major-version', str(devel_version.major)] + cwd = str(devel_dir) else: - latest_filename = find_latest_deps_file(build_data_working, ansible_version) + latest_deps_file, ansible_version_ver = find_latest_deps_file(build_data_working, ansible_version) + deps_dir = os.path.dirname(latest_deps_file) # Make a copy of the deps file so that we can set the ansible-core version we'll use modified_deps_file = os.path.join(tmp_dir, 'ansible.deps') - shutil.copyfile(latest_filename, modified_deps_file) + shutil.copyfile(latest_deps_file, modified_deps_file) + + # Make a copy of collection-meta.yaml + shutil.copyfile(os.path.join(deps_dir, 'collection-meta.yaml'), os.path.join(tmp_dir, 'collection-meta.yaml')) # Put our version of ansible-core into the deps file deps_data = parse_deps_file(modified_deps_file) @@ -182,12 +196,23 @@ def generate_full_docs(args): write_deps_file(modified_deps_file, deps_data) - params = ['stable', '--deps-file', modified_deps_file] + params = ['stable', '--deps-file', 'ansible.deps', '--version', str(ansible_version_ver)] + cwd = str(tmp_dir) - # Generate the plugin rst - return antsibull_docs.run(['antsibull-docs'] + params + - ['--ansible-core-source', str(args.top_dir), - '--dest-dir', args.output_dir]) + old_cwd = os.getcwd() + try: + os.chdir(cwd) + # Generate the plugin rst + full_command = ['antsibull-docs'] + params + [ + '--ansible-core-source', + os.path.join(old_cwd, str(args.top_dir)), + '--dest-dir', + os.path.join(old_cwd, args.output_dir), + ] + print(f"Running {full_command!r} in {cwd!r}:") + return antsibull_docs.run(full_command) + finally: + os.chdir(old_cwd) # If we make this more than just a driver for antsibull: # Run other rst generation @@ -199,7 +224,6 @@ class CollectionPluginDocs(Command): _ACTION_HELP = """Action to perform. full: Regenerate the rst for the full ansible website. core: Regenerate the rst for plugins in ansible-core and then build the website. - named: Regenerate the rst for the named plugins and then build the website. """ @classmethod @@ -212,7 +236,7 @@ class CollectionPluginDocs(Command): ' hierarchy.') # I think we should make the actions a subparser but need to look in git history and see if # we tried that and changed it for some reason. - parser.add_argument('action', action='store', choices=('full', 'core', 'named'), + parser.add_argument('action', action='store', choices=('full', 'core'), default='full', help=cls._ACTION_HELP) parser.add_argument("-o", "--output-dir", action="store", dest="output_dir", default=DEFAULT_OUTPUT_DIR, @@ -249,7 +273,7 @@ class CollectionPluginDocs(Command): if args.action == 'core': return generate_core_docs(args) - # args.action == 'named' (Invalid actions are caught by argparse) - raise NotImplementedError('Building docs for specific files is not yet implemented') + + raise NotImplementedError('New actions have to be explicitly supported by the code') # return 0