docs: def generate_catalog(xsd_schemas=None, xmlcatalog_dir=None, xmlcatalog_file=None):
      """Generating an XML catalog for use in resolving schemas
  
      Creates the XML Catalog directory if it doesn't already exist.
      Uses :meth:`download_schema` to save local copies of schemas,
      adding a comment indicating the date downloaded by eulxml.
  
      Generates a new catalog.xml file, with entries for all schemas
      that downloaded successfully.  If no schemas downloaded, the catalog
      is not generated.
  
      .. Note::
  
          Currently this method overwites any existing schema and catalog
          files, without checking if they are present or need to be
          updated.
  
      """
      # if requests isn't available, warn and bail out
      if requests is None:
          sys.stderr.write(req_requests_msg)
          return
  
      logger.debug("Generating a new XML catalog")
      if xsd_schemas is None:
          xsd_schemas = XSD_SCHEMAS
  
      if xmlcatalog_file is None:
          xmlcatalog_file = XMLCATALOG_FILE
  
      if xmlcatalog_dir is None:
          xmlcatalog_dir = XMLCATALOG_DIR
      # if the catalog dir doesn't exist, create it
      if not os.path.isdir(xmlcatalog_dir):
          os.mkdir(xmlcatalog_dir)
  
      # new xml catalog to be populated with saved schemas
      catalog = Catalog()
  
      # comment string to be added to locally-saved schemas
      comment = 'Downloaded by eulxml %s on %s' % \
          (__version__, date.today().isoformat())
  
      for schema_uri in xsd_schemas:
          filename = os.path.basename(schema_uri)
          schema_path = os.path.join(xmlcatalog_dir, filename)
          saved = download_schema(schema_uri, schema_path, comment)
          if saved:
              # if download succeeded, add to our catalog.
              # - name is the schema identifier (uri)
              # - uri is the local path to load
              # NOTE: using path relative to catalog file
              catalog.uri_list.append(Uri(name=schema_uri, uri=filename))
  
      # if we have any uris in our catalog, write it out
      if catalog.uri_list:
          with open(xmlcatalog_file, 'wb') as xml_catalog:
              catalog.serializeDocument(xml_catalog, pretty=True)
      return catalog