docs: def publish():
      """Publishes Formic to PyPi (don't run unless you are the maintainer)"""
      print("To be ready for release, remember:")
      print("      1) Update the version number (and associated test)")
      print("      2) Update the ChangeLog.rst (and other documentation)")
      print(
          "         ChangeLog should have an line (title) consisting of the version number"
      )
      print("      3) Tag Mercurial with 'Release <version>'")
      print("      4) Push updates to BitBucket")
      print("      5) Set the RELEASE environment variable")
      print("           $ export RELEASE=formic")
  
      cmd = [
          'bash', '-c',
          'yolk -M formic | grep "^version: " | sed "s/^version: \\(.*\\)$/\\1/"'
      ]
      published_version = subprocess.check_output(cmd).strip()
      our_version = open(os.path.join("formic", "VERSION.txt"), "r").read()
  
      # sanity test on version
      if "\n" in published_version or\
         len(published_version) < 3 or len(published_version) > 10:
          raise Exception(
              "Published version number seems weird: " + published_version)
  
      print("Published version:", published_version)
      print("Current version:  ", our_version)
  
      if our_version == published_version:
          raise Exception(
              "You are attempting to republish version " + our_version)
  
      # sanity: check ChangeLog starts with our version
      changelog = open("CHANGELOG.rst", "r")
      found = False
      for line in changelog.readlines():
          if line.strip() == our_version:
              print("ChangeLog has an entry")
              found = True
              break
      changelog.close()
      if not found:
          raise Exception(
              "The ChangeLog does not appear to include comments on this release"
          )
  
      # Sanity check: is there a release tag
      tags = subprocess.check_output("hg tags".split())
      found = False
      looking_for = "Release " + our_version
      for line in tags.split("\n"):
          match = re.match(r"^(.*)\s+[0-9]+:[0-9a-f]+$", line)
          if match:
              tag = match.group(1).strip()
              if tag == looking_for:
                  print("Found tag", tag)
                  found = True
                  break
  
      if not found:
          raise Exception(
              "Mercurial does not have the release tag: " + looking_for)
  
      status = subprocess.check_output(["hg", "status"])
      for line in status.split("\n"):
          if len(line) > 0:
              raise Exception("Uncommitted changes present")
  
      try:
          v = os.environ["RELEASE"]
          if v != "formic":
              raise KeyError()
      except KeyError:
          print("$RELEASE environment variable is not set")
          raise
  
      subprocess.check_call("python setup.py bdist_egg upload".split())
      subprocess.check_call("python setup.py sdist upload".split())