'Make a reST API index file from written files
Parameters
path : string
Filename to write index to
outdir : string
Directory to which to write generated index file
froot : string, optional
root (filename without extension) of filename to write to
Defaults to \'gen\'.  We add ``self.rst_extension``.
relative_to : string
path to which written filenames are relative.  This
component of the written file path will be removed from
outdir, in the generated index.  Default is None, meaning,
leave path as it is.'

def write_index(self, outdir, froot='gen', relative_to=None):

    if (self.written_modules is None):
        raise ValueError('No    modules    written')
    path = os.path.join(outdir, (froot + self.rst_extension))
    if (relative_to is not None):
        relpath = outdir.replace((relative_to + os.path.sep), '')
    else:
        relpath = outdir
    idx = open(path, 'wt')
    w = idx.write
    w('..    AUTO-GENERATED    FILE    --    DO    NOT    EDIT!\n\n')
    w('..    toctree::\n\n')
    for f in self.written_modules:
        w(('            %s\n' % os.path.join(relpath, f)))
    idx.close()
