On-the-fly switching between remote/local Sphinx objects.inv sourcing via an environment variable

env_objectsinv.md

Description

There are various situations where it's problematic for intersphinx to always retrieve objects.inv files from their network locations. The major such situations are where network access is unavailable, or very slow. As well, the downloads do always take some time, and thus local caching can usually provide speed benefits on every make.

The below is a Python 3 implementation of an environment variable-controlled switch between remote retrieval of objects.inv files and retrieval from a local cache. As written, if the envvar ISPHX_LOCAL is set to any truthy value, Sphinx will retrieve from local cache. If ISPHX_LOCAL is absent or falsey, then Sphinx will pull from the remote location.

The local cache can be updated by running python3 objpull.py from within the doc/source/isphx directory.

The controlling envvar and the subdirectory within doc/source to hold the local objects.inv cache can be changed in conf.py and it should work fine. If you change the name isphx_objstr, you'll also have to change the variable in objpull.py, too.

Changes in conf.py
Probably best to include at the end

isphx_local = os.environ.get('ISPHX_LOCAL')
isphx_objpath = os.path.join('isphx', '{0}')
isphx_objstr = 'objects_{0}.inv'


def isphx_subst(s):
    return isphx_objpath.format(isphx_objstr.format(s)) if isphx_local else None

intersphinx_mapping = {
    'python': ('https://docs.python.org/3.5', isphx_subst('python')),
    'numpy': ('https://docs.scipy.org/doc/numpy/', isphx_subst('numpy')),
    'scipy': ('http://docs.scipy.org/doc/scipy/reference', isphx_subst('scipy')),
    'h5py': ('http://docs.h5py.org/en/latest/', isphx_subst('h5py')),
    'sphinx': ('http://www.sphinx-doc.org/en/stable/', isphx_subst('sphinx'))
    }

Contents of doc/source/isphx/objpull.py

# Quickie script for refreshing the local objects.inv cache
# OVERWRITES EXISTING FILES, WITH PRE-DELETION


def pullobjs():

    import os
    import wget

    # Open conf.py, retrieve content and compile
    with open(os.path.join(os.pardir, 'conf.py'), 'r') as f:
        confcode = compile(f.read(), 'conf.py', 'exec')

    # Execute conf.py into the global namespace (I know, sloppy)
    exec(confcode, globals())

    # Iterate intersphinx_mapping from conf.py to retrieve the objects.inv files
    # Make use of the conf.py 'isphx_objstr' substitution string, too
    for n, t in intersphinx_mapping.items():

        print('{0}:'.format(n))

        try:
            os.remove(isphx_objstr.format(n))
        except FileNotFoundError:
            pass # No big deal

        wget.download(url=t[0] + '/objects.inv', out=isphx_objstr.format(n))

        print('\n')


if __name__ == '__main__':

    pullobjs()