linkcheck_ignore = [
    # Random location to store ignored locations for `linkcheck_check_cache`
    r'/dev/null',
]

def linkcheck_check_cache(app: Sphinx, uri: str) -> str | None:
    # Get the cache result files
    cache_file = app.outdir / "linkcheck_cache.json"
    now = datetime.datetime.now(datetime.UTC)
    cache_file.touch()
    with cache_file.open("rt") as f:
        try:
            cache_data = json.load(f)
        except JSONDecodeError:
            cache_data = {}
    # Check if we have cached this uri yet
    if uri in cache_data:
        # Check if the cache data is recent enough
        cached_time = datetime.datetime.fromtimestamp(cache_data[uri], datetime.UTC)
        age = (now - cached_time).total_seconds()
        if age < 108000.0:
            # cache is relatively recent, so we skip this uri
            # right now we use a random location to match a hard-coded regex
            return "/dev/null"
    # If either check fails, we want to do the check and update the cache
    cache_data[uri] = now.timestamp()
    with cache_file.open("wt") as f:
        json.dump(cache_data, f)
    return uri


def setup(app: Sphinx) -> None:
    # Check a cached version of the linkcheck results
    app.connect("linkcheck-process-uri", linkcheck_check_cache)