"""Custom mkdocs hooks, using the mkdocs-simple-hooks plugin.""" import json import os import re from datetime import datetime from distutils.version import StrictVersion import requests def fetch_rtd_versions(): """Get a list of RTD docs versions to build the version selector.""" print('Fetching documentation versions from ReadTheDocs') versions = [] def make_request(url, headers): """Make a single request to the RTD API.""" response = requests.get(url, headers=headers) if response.status_code != 200: print(f'Error fetching RTD versions: {response.status_code}') return data = json.loads(response.text) for entry in data['results']: slug = entry['slug'] ref = entry['ref'] url = entry['urls']['documentation'] aliases = [] if ref is not None: aliases.append(slug) version = ref or slug if version == 'latest': continue versions.append({'version': version, 'title': version, 'aliases': aliases}) if data['next']: make_request(data['next'], headers) # Fetch the list of versions from the RTD API token = os.environ.get('RTD_TOKEN', None) if token: headers = {'Authorization': f'Token {token}'} url = 'https://readthedocs.org/api/v3/projects/inventree/versions/?active=true&limit=50' make_request(url, headers) else: print('No RTD token found - skipping RTD version fetch') # Sort versions by version number versions = sorted(versions, key=lambda x: StrictVersion(x['version']), reverse=True) # Add "latest" version first if not any(x['title'] == 'latest' for x in versions): versions.insert( 0, { 'title': 'Development', 'version': 'latest', 'aliases': ['main', 'latest', 'development'], }, ) # Ensure we have the 'latest' version current_version = os.environ.get('READTHEDOCS_VERSION', None) if current_version and not any(x['title'] == current_version for x in versions): versions.append({ 'version': current_version, 'title': current_version, 'aliases': [], }) output_filename = os.path.join(os.path.dirname(__file__), 'versions.json') print('Discovered the following versions:') print(versions) with open(output_filename, 'w', encoding='utf-8') as file: json.dump(versions, file, indent=2) def get_release_data(): """Return InvenTree release information. - First look to see if 'releases.json' file exists - If data does not exist in this file, request via the github API """ json_file = os.path.join(os.path.dirname(__file__), 'releases.json') releases = [] if os.path.exists(json_file): # Release information has been cached to file print("Loading release information from 'releases.json'") with open(json_file, encoding='utf-8') as f: return json.loads(f.read()) # Download release information via the GitHub API print('Fetching InvenTree release information from api.github.com:') releases = [] # Keep making API requests until we run out of results page = 1 while 1: url = f'https://api.github.com/repos/inventree/inventree/releases?page={page}&per_page=150' response = requests.get(url, timeout=30) assert response.status_code == 200 data = json.loads(response.text) if len(data) == 0: break for item in data: releases.append(item) page += 1 # Cache these results to file with open(json_file, 'w', encoding='utf-8') as f: print("Saving release information to 'releases.json'") f.write(json.dumps(releases)) return releases def on_config(config, *args, **kwargs): """Run when the mkdocs config is loaded. We want to be able to provide a *dynamic* config.site_url parameter to mkdocs, which tells it the base url, e.g. - https://readthedocs.io/en/latest - https://readthedocs.io/de/0.5.1 Further, we need to know if we are building on readthedocs at all! readthedocs provides some environment variables: - https://docs.readthedocs.io/en/stable/builds.html#build-environment We can use these to determine (at run time) where we are hosting """ rtd = os.environ.get('READTHEDOCS', False) # Check for 'versions.json' file # If it does not exist, we need to fetch it from the RTD API if os.path.exists(os.path.join(os.path.dirname(__file__), 'versions.json')): print("Found 'versions.json' file") else: fetch_rtd_versions() if rtd: rtd_version = os.environ['READTHEDOCS_VERSION'] rtd_language = os.environ['READTHEDOCS_LANGUAGE'] site_url = f'https://docs.inventree.org/{rtd_language}/{rtd_version}' assets_dir = f'/{rtd_language}/{rtd_version}/assets' print('Building within READTHEDOCS environment!') print(f' - Version: {rtd_version}') print(f' - Language: {rtd_language}') # Add *all* readthedocs related keys readthedocs = {} for key in os.environ: if key.startswith('READTHEDOCS_'): k = key.replace('READTHEDOCS_', '').lower() readthedocs[k] = os.environ[key] # Supply this to the context config['readthedocs'] = readthedocs # Determine if we want to display a 'version' banner # Basically we do, *unless* we are displaying the "stable" version config['version_banner'] = rtd_version != 'stable' else: print("'READTHEDOCS' environment variable not found") print('Building for localhost configuration!') assets_dir = '/assets' site_url = config['site_url'] config['readthedocs'] = False config['assets_dir'] = assets_dir config['site_url'] = site_url print(f"config.site_url = '{site_url}'") print(f"config.assets_dir = '{assets_dir}'") release_data = get_release_data() releases = [] for item in release_data: # Ignore draft releases if item['draft']: continue tag = item['tag_name'] # Check that the tag is formatted correctly re.match(r'^\d+\.\d+\.\d+$', tag) if not re.match: print(f'Found badly formatted release: {tag}') continue # Check if there is a local file with release information local_path = os.path.join(os.path.dirname(__file__), 'releases', f'{tag}.md') if os.path.exists(local_path): item['local_path'] = local_path # Extract the date item['date'] = item['published_at'].split('T')[0] date = datetime.fromisoformat(item['date']) # First tagged docker release was 2021-04-18 if date > datetime(year=2021, month=4, day=17): item['docker'] = True # Add a "prefix" so we can split by sub version item['prefix'] = '.'.join(tag.split('.')[:-1]) releases.append(item) print(f'- found {len(releases)} releases.') # Sort releases by descending date config['releases'] = sorted(releases, key=lambda it: it['date'], reverse=True) return config