docs: def discover_setup_packages():
      """Summarize packages currently set up by EUPS, listing their
      set up directories and EUPS version names.
  
      Returns
      -------
      packages : `dict`
         Dictionary with keys that are EUPS package names. Values are
         dictionaries with fields:
  
         - ``'dir'``: absolute directory path of the set up package.
         - ``'version'``: EUPS version string for package.
  
      Notes
      -----
      This function imports the ``eups`` Python package, which is assumed to
      be available in the build environmen. This function is designed to
      encapsulate all direct EUPS interactions need by the stack documentation
      build process.
      """
      logger = logging.getLogger(__name__)
  
      # Not a PyPI dependency; assumed to be available in the build environment.
      import eups
  
      eups_client = eups.Eups()
      products = eups_client.getSetupProducts()
  
      packages = {}
      for package in products:
          name = package.name
          info = {
              'dir': package.dir,
              'version': package.version
          }
          packages[name] = info
          logger.debug('Found setup package: {name} {version} {dir}'.format(
              name=name, **info))
  
      return packages