mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
4.2 KiB
Python
102 lines
4.2 KiB
Python
# -*- coding: utf-8 -*-
|
|
# (c) 2020, Ansible Project
|
|
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
|
|
|
# Make coding more python3-ish
|
|
from __future__ import (absolute_import, division, print_function)
|
|
__metaclass__ = type
|
|
|
|
|
|
import argparse
|
|
import importlib
|
|
import os
|
|
import pathlib
|
|
import time
|
|
import urllib.parse
|
|
|
|
from collections import defaultdict
|
|
|
|
from ansible.module_utils.common.collections import is_iterable
|
|
from ansible.module_utils.urls import Request
|
|
|
|
# Pylint doesn't understand Python3 namespace modules.
|
|
from ..commands import Command # pylint: disable=relative-beyond-top-level
|
|
from .. import errors # pylint: disable=relative-beyond-top-level
|
|
|
|
|
|
EXAMPLE_CONF = """
|
|
A proper intersphinx_mapping entry should look like:
|
|
intersphinx_mapping = {
|
|
'python3': ('https://docs.python.org/3', (None, 'python3.inv'))
|
|
}
|
|
|
|
See the intersphinx docs for more info:
|
|
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping
|
|
"""
|
|
|
|
|
|
class UpdateIntersphinxCache(Command):
|
|
name = 'update-intersphinx-cache'
|
|
|
|
@classmethod
|
|
def init_parser(cls, add_parser):
|
|
parser = add_parser(cls.name, description='Update cached intersphinx mappings. This'
|
|
' updates the cached intersphinx mappings for docs to reference'
|
|
' documentation from other projects.')
|
|
parser.add_argument('-o', '--output-dir', action='store',
|
|
help='Path to directory the cached objects.inv files are stored in')
|
|
parser.add_argument('-c', '--conf-file', action='store',
|
|
help='Path to a sphinx config file to retrieve intersphinx config from')
|
|
|
|
@staticmethod
|
|
def main(args):
|
|
# Retrieve the intersphinx information from the sphinx config file
|
|
conf_dir = pathlib.Path(args.conf_file).parent
|
|
|
|
conf_module_spec = importlib.util.spec_from_file_location('sphinxconf', args.conf_file)
|
|
conf_module = importlib.util.module_from_spec(conf_module_spec)
|
|
conf_module_spec.loader.exec_module(conf_module)
|
|
intersphinx_mapping = conf_module.intersphinx_mapping
|
|
|
|
for intersphinx_name, inventory in intersphinx_mapping.items():
|
|
if not is_iterable(inventory) or len(inventory) != 2:
|
|
print('WARNING: The intersphinx entry for {0} must be'
|
|
' a two-tuple.\n{1}'.format(intersphinx_name, EXAMPLE_CONF))
|
|
continue
|
|
|
|
url = cache_file = None
|
|
for inv_source in inventory:
|
|
if isinstance(inv_source, str) and url is None:
|
|
url = inv_source
|
|
elif is_iterable(inv_source) and cache_file is None:
|
|
if len(inv_source) != 2:
|
|
print('WARNING: The fallback entry for {0} should be a tuple of (None,'
|
|
' filename).\n{1}'.format(intersphinx_name, EXAMPLE_CONF))
|
|
continue
|
|
cache_file = inv_source[1]
|
|
else:
|
|
print('WARNING: The configuration for {0} should be a tuple of one url and one'
|
|
' tuple for a fallback filename.\n{1}'.format(intersphinx_name,
|
|
EXAMPLE_CONF))
|
|
continue
|
|
|
|
if url is None or cache_file is None:
|
|
print('WARNING: Could not figure out the url or fallback'
|
|
' filename for {0}.\n{1}'.format(intersphinx_name, EXAMPLE_CONF))
|
|
continue
|
|
|
|
url = urllib.parse.urljoin(url, 'objects.inv')
|
|
# Resolve any relative cache files to be relative to the conf file
|
|
cache_file = conf_dir / cache_file
|
|
|
|
# Retrieve the inventory and cache it
|
|
# The jinja CDN seems to be blocking the default urllib User-Agent
|
|
requestor = Request(headers={'User-Agent': 'Definitely Not Python ;-)'})
|
|
with requestor.open('GET', url) as source_file:
|
|
with open(cache_file, 'wb') as f:
|
|
f.write(source_file.read())
|
|
|
|
print('Download of new cache files complete. Remember to git commit -a the changes')
|
|
|
|
return 0
|