inventree-docs/docs/hooks.py

"""
Custom mkdocs hooks, using the mkdocs-simple-hooks plugin
"""

import json
import os
import re

from datetime import datetime
from urllib import request


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) as f:
            releases = json.loads(f.read())
    else:
        
        # 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"

            print(f" - {url}")

            response = request.urlopen(url, timeout=30)
            assert(response.status == 200)

            data = json.loads(response.read().decode())

            if len(data) == 0:
                break
            
            for item in data:
                releases.append(item)

            page += 1

        # Cache these results to file
        with open(json_file, 'w') as f:
            print("Saving release information to 'releases.json'")
            f.write(json.dumps(releases))
    
    return releases

def on_config(config, *args, **kwargs):
    """
    Hosting multiple versions of the documenation on readthedocs.io is complex,
    as the required interactions between rtd and mkdocs do not exist.

    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)

    if rtd:
        rtd_version = os.environ['READTHEDOCS_VERSION']
        rtd_language = os.environ['READTHEDOCS_LANGUAGE']

        site_url = f"https://inventree.readthedocs.io/{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.keys():
            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('^\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