docs: def log_the_survey_settings(
          log,
          pathToYamlFile):
      """
      *Create a MD log of the survey settings*
  
      **Key Arguments:**
          - ``log`` -- logger
          - ``pathToYamlFile`` -- yaml results file
  
      **Return:**
          - None
      """
      ################ > IMPORTS ################
      ## STANDARD LIB ##
      ## THIRD PARTY ##
      import yaml
      ## LOCAL APPLICATION ##
      from datetime import datetime, date, time
      now = datetime.now()
      now = now.strftime("%Y%m%dt%H%M%S")
  
      ################ >ACTION(S) ################
      # IMPORT THE SIMULATION SETTINGS
      fileName = pathToYamlFile
      stream = file(fileName, 'r')
      yamlContent = yaml.load(stream)
      snSurveyDiscoveryTimes = yamlContent['Discoveries Relative to Survey Year']
      lightCurveDiscoveryTimes = yamlContent[
          'Discoveries Relative to Peak Magnitudes']
      snTypes = yamlContent['SN Types']
      redshifts = yamlContent['Redshifts']
      cadenceDictionary = yamlContent['Cadence Dictionary']
      peakAppMagList = yamlContent['Peak Apparent Magnitudes']
      snCampaignLengthList = yamlContent['Campaign Length']
  
      programSettings = yamlContent["Program Settings"]
  
      limitingMags = yamlContent["Limiting Magnitudes"]
      # for key in limitingMags:
      # log.debug('filter: %s, limit: %s' % (key, limitingMags[key]))
  
      sampleNumber = yamlContent["Simulation Sample"]
  
      peakMagnitudeDistributions = yamlContent[
          "SN Absolute Peak-Magnitude Distributions"]
      #log.debug('snDistributions[magnitude] %s' % (snDistributions["magnitude"],))
      #log.debug('snDistributions[sigma] %s' % (snDistributions["sigma"],))
  
      relativeRatesSet = yamlContent["Relative Rate Set to Use"]
      relativeSNRates = yamlContent["Relative SN Rates"][relativeRatesSet]
      #log.debug('relativeSNRates %s' % (relativeSNRates,))
      lowerRedshiftLimit = yamlContent["Lower Redshift Limit"]
      upperRedshiftLimit = yamlContent["Upper Redshift Limit"]
      #log.debug('upperRedshiftLimit %s' % (upperRedshiftLimit,))
      redshiftResolution = yamlContent["Redshift Resolution"]
  
      extinctionSettings = yamlContent["Extinctions"]
      extinctionType = extinctionSettings["constant or random"]
  
      hostExtinctionDistributions = extinctionSettings["host"]
      #log.debug('hostExtinctionDistributions %s' % (hostExtinctionDistributions,))
      galacticExtinctionDistribution = extinctionSettings["galactic"]
      #log.debug('galacticExtinctionDistribution %s' % (galacticExtinctionDistribution,))
  
      surveyCadenceSettings = yamlContent["Survey Cadence"]
      #log.debug('surveyCadenceSettings %s' % (surveyCadenceSettings,))
  
      snLightCurves = yamlContent["Lightcurves"]
      #log.debug('snlightCurves %s' % (snlightCurves,))
  
      surveyArea = yamlContent["Sky Area of the Survey (square degrees)"]
  
      extraSurveyConstraints = yamlContent["Extra Survey Constraints"]
  
      weatherLossFraction = surveyCadenceSettings[
          "Fraction of Year Lost to Weather etc"]
      observableFraction = surveyCadenceSettings["Observable Fraction of Year"]
      extinctionConstant = extinctionSettings["constant E(b-v)"]
      CCSNRateFraction = yamlContent[
          "CCSN Progenitor Population Fraction of IMF"]
      transientToCCSNRateFraction = yamlContent["Transient to CCSN Ratio"]
      restFrameFilter = yamlContent["Rest Frame Filter for K-corrections"]
      peakMagLimit = extraSurveyConstraints["Faint-Limit of Peak Magnitude"]
      campaignLengthLimit = extraSurveyConstraints[
          "Observable for at least ? number of days"]
  
      # CALCULATE THE SURVEY VOLUME
      c = converter(log=log)
      dists = c.redshift_to_distance(
          z=float(upperRedshiftLimit),
          WM=0.3,
          WV=0.7,
          H0=70.0
      )
      dl_mpc = dists["dl_mpc"]
      sphereOuter = (4. / 3.) * math.pi * dl_mpc**3
  
      if float(lowerRedshiftLimit) == 0.:
          surveyVolume = sphereOuter
      else:
          dists = c.redshift_to_distance(
              z=float(lowerRedshiftLimit),
              WM=0.3,
              WV=0.7,
              H0=70.0
          )
          dl_mpc = dists["dl_mpc"]
          sphereInner = (4. / 3.) * math.pi * dl_mpc**3
          surveyVolume = sphereOuter - sphereInner
      # NOW SCALE TO SKY-AREA
      surveyVolume = surveyVolume * surveyArea / 41253
      surveyVolume = surveyVolume / (1000.)**3
      if surveyVolume < 1:
          surveyVolume = "%(surveyVolume)0.4f" % locals()
      elif surveyVolume < 100:
          surveyVolume = "%(surveyVolume)0.2f" % locals()
      else:
          surveyVolume = "%(surveyVolume)0.1f" % locals()
  
      # CALCULATE OVERALL DETECTION FRACTIONS
      discoveryFraction, tooFaintFraction, shortCampaignFraction = calculate_fraction_of_sn_discovered(
          log, surveyCadenceSettings, snSurveyDiscoveryTimes, redshifts, peakAppMagList, snCampaignLengthList, extraSurveyConstraints, lowerRedshiftLimit, upperRedshiftLimit)
  
      discoveryFraction = discoveryFraction * 100.
      if discoveryFraction < 1:
          discoveryFraction = "%(discoveryFraction)0.4f" % locals()
      elif discoveryFraction < 10:
          discoveryFraction = "%(discoveryFraction)0.2f" % locals()
      else:
          discoveryFraction = "%(discoveryFraction)0.1f" % locals()
  
      # log.info('yamlContent %s' % (yamlContent,))
      stream.close()
  
      settings_log = """
  # SN Survey Simulation Results - %s
  
  The *%s*-band liming magnitudes of this simulated survey are:
  
  | Filter | Magnitude |
  |:---|:----|
  """ % (now, restFrameFilter)
      for k, v in limitingMags.iteritems():
          settings_log += """| %s | %s |\n""" % (k, v,)
      settings_log += """
  
  A total of **%s** transients where simulated in the survey, within a **redshift-range of %s-%s** and **survey footprint of %s deg<sup>2</sup>** (a **total volume of %s Gpc<sup>-3</sup> yr<sup>-1</sup>**). **%s%% of these simulated transients had solid 'discoveries'**.  A constant galactic extinction of `E(B-V) = %s` is used, it's assumed that any given field in the sky is visible for %s of the survey year and the typical fraction of survey time lost to weather of %s is accounted for. Here are the relative rates and peak magnitude distributions of the SN used in the survey:
  
  | SN Type | Relative Rate | Peak Magnitude | Sigma Peak |
  |:---|:---|:---|:---|
  """ % (sampleNumber, lowerRedshiftLimit, upperRedshiftLimit, surveyArea, surveyVolume, discoveryFraction, extinctionConstant, observableFraction, weatherLossFraction,)
      for k, v in peakMagnitudeDistributions['magnitude'].iteritems():
          settings_log += """| %s | %s | %s | %s |\n""" % (
              k, relativeSNRates[k], v, peakMagnitudeDistributions['sigma'][k])
      settings_log += """
  
  If a transient is detected by the simulated survey, extra constraints are placed upon the detected object to secure positive identification as the object.
  
  1. The peak apparent magnitude of the object must be brighter than **%s mag**
  2. The object must be detectable for long enough to complete a follow-up campaign of longer than **%s days** within 1 survey year with any single filter.
  
  The transient rate for the survey volume is estimated by assuming a rate of **%s** times that of the CCSN rate (itself a fraction of **%s** of the total SFR).
  
  """ % (peakMagLimit, campaignLengthLimit, transientToCCSNRateFraction, CCSNRateFraction)
      return settings_log