Build a `dict` of Sphinx configurations that populate the ``conf.py``
    of the main pipelines_lsst_io Sphinx project for LSST Science Pipelines
    documentation.

    The ``conf.py`` file can ingest these configurations via::

       from documenteer.sphinxconfig.stackconf import \
           build_pipelines_lsst_io_configs

       _g = globals()
       _g.update(build_pipelines_lsst_io_configs(
           project_name='LSST Science Pipelines')

    You can subsequently customize the Sphinx configuration by directly
    assigning global variables, as usual in a Sphinx ``config.py``, e.g.::

       copyright = '2016 Association of Universities for '
                   'Research in Astronomy, Inc.'

    Parameters
    ----------
    project_name : `str`
        Name of the project
    copyright : `str`, optional
        Copyright statement. Do not include the 'Copyright (c)' string; it'll
        be added automatically.

    Returns
    -------
    c : dict
        Dictionary of configurations that should be added to the ``conf.py``
        global namespace via::

            _g = global()
            _g.update(c)

def build_pipelines_lsst_io_configs(*, project_name, copyright=None):
    """Build a `dict` of Sphinx configurations that populate the ``conf.py``
    of the main pipelines_lsst_io Sphinx project for LSST Science Pipelines
    documentation.

    The ``conf.py`` file can ingest these configurations via::

       from documenteer.sphinxconfig.stackconf import \
           build_pipelines_lsst_io_configs

       _g = globals()
       _g.update(build_pipelines_lsst_io_configs(
           project_name='LSST Science Pipelines')

    You can subsequently customize the Sphinx configuration by directly
    assigning global variables, as usual in a Sphinx ``config.py``, e.g.::

       copyright = '2016 Association of Universities for '
                   'Research in Astronomy, Inc.'

    Parameters
    ----------
    project_name : `str`
        Name of the project
    copyright : `str`, optional
        Copyright statement. Do not include the 'Copyright (c)' string; it'll
        be added automatically.

    Returns
    -------
    c : dict
        Dictionary of configurations that should be added to the ``conf.py``
        global namespace via::

            _g = global()
            _g.update(c)
    """
    # Work around Sphinx bug related to large and highly-nested source files
    sys.setrecursionlimit(2000)

    c = {}

    c = _insert_common_sphinx_configs(
        c,
        project_name=project_name)

    # HTML theme
    c = _insert_html_configs(
        c,
        project_name=project_name,
        short_project_name=project_name)

    # Sphinx extension modules
    c = _insert_extensions(c)

    # Intersphinx configuration
    c = _insert_intersphinx_mapping(c)

    # Breathe extension configuration
    # FIXME configure this for multiple sites

    # Automodapi and numpydoc configurations
    c = _insert_automodapi_configs(c)

    # Matplotlib configurations
    c = _insert_matplotlib_configs(c)

    # Graphviz configurations
    c = _insert_graphviz_configs(c)

    # Add versioning information
    c = _insert_eups_version(c)

    # Always use "now" as the date for the main site's docs because we can't
    # look at the Git history of each stack package.
    date = datetime.datetime.now()
    c['today'] = date.strftime('%Y-%m-%d')

    # Use this copyright for now. Ultimately we want to gather COPYRIGHT files
    # and build an integrated copyright that way.
    c['copyright'] = '2015-{year} LSST contributors'.format(
        year=date.year)

    # Hide todo directives in the "published" documentation on the main site.
    c['todo_include_todos'] = False

    # List of patterns, relative to source directory, that match files and
    # directories to ignore when looking for source files.
    c['exclude_patterns'] = [
        'README.rst',
        # Build products
        '_build',
        # Source for release notes (contents are included in built pages)
        'releases/note-source/*.rst',
        'releases/tickets-source/*.rst',
        # EUPS configuration directory
        'ups',
        # Recommended directory for pip installing doc eng Python packages
        '.pyvenv',
        # GitHub templates
        '.github',
        # This 'home' directory is created by the docubase image for the
        # sqre/infra/documenteer ci.lsst.codes Jenkins job. Ideally this
        # shouldn't be in the directory at all, but we certainly need to
        # ignore it while its here.
        'home',
    ]

    # Insert rst_epilog configuration
    c = _insert_rst_epilog(c)

    # Set up the context for the sphinx-jinja extension
    c = _insert_jinja_configuration(c)

    return c