Builds a `dict` of Sphinx configurations useful for the ``doc/conf.py``
    files of individual LSST Stack packages.

    The ``doc/conf.py`` of packages can ingest these configurations via::

       from documenteer.sphinxconfig.stackconf import build_package_configs

       _g = globals()
       _g.update(build_package_configs(
           project_name='afw',
           version=lsst.afw.version.__version__))

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

    .. code:: python

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

    Parameters
    ----------
    project_name : str
        Name of the package.
    copyright : str, optional
        Copyright statement. Do not include the 'Copyright (c)' string; it'll
        be added automatically.
    version : str
        Version string. Use the ``__version__`` member in a package's
        ``version`` module.
    doxygen_xml_dirname : str
        Path to doxygen-generated XML, allowing C++ APIs to be documented
        through breathe. If not set, the breathe sphinx extension will not be
        enabled.

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

            _g = global()
            _g.update(c)

def build_package_configs(project_name,
                          version=None,
                          copyright=None,
                          doxygen_xml_dirname=None):
    """Builds a `dict` of Sphinx configurations useful for the ``doc/conf.py``
    files of individual LSST Stack packages.

    The ``doc/conf.py`` of packages can ingest these configurations via::

       from documenteer.sphinxconfig.stackconf import build_package_configs

       _g = globals()
       _g.update(build_package_configs(
           project_name='afw',
           version=lsst.afw.version.__version__))

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

    .. code:: python

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

    Parameters
    ----------
    project_name : str
        Name of the package.
    copyright : str, optional
        Copyright statement. Do not include the 'Copyright (c)' string; it'll
        be added automatically.
    version : str
        Version string. Use the ``__version__`` member in a package's
        ``version`` module.
    doxygen_xml_dirname : str
        Path to doxygen-generated XML, allowing C++ APIs to be documented
        through breathe. If not set, the breathe sphinx extension will not be
        enabled.

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

            _g = global()
            _g.update(c)
    """
    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
    c = _insert_breathe_configs(
        c,
        project_name=project_name,
        doxygen_xml_dirname=doxygen_xml_dirname)

    # 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_single_package_eups_version(c, version)

    try:
        date = read_git_commit_timestamp()
    except Exception:
        date = datetime.datetime.now()

    if copyright is not None:
        c['copyright'] = copyright
    else:
        c['copyright'] = '{:s} LSST contributors'.format(
            date.strftime('%Y'))

    c['today'] = date.strftime('%Y-%m-%d')

    # List of patterns, relative to source directory, that match files and
    # directories to ignore when looking for source files.
    c['exclude_patterns'] = [
        '_build',
        'README.rst',
    ]

    # Show rendered todo directives in package docs since they're developer
    # facing.
    c['todo_include_todos'] = True

    # 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