docs: def reference(text=None, label=None):
      """Add a reference to the bibliography and insert a superscript number.
  
      Parameters
      ----------
      text : `string`, optional
          The complete text of the reference, e.g. Roo, et al. "How to Python." Nature, 2019.
      label : `string`, optional
          A short label to describe this reference.
  
      Notes
      -----
      1) Every time reference() is called, the reference number is auto-incremented. That is, the first
         time you call this, a superscript 1 is inserted. The next time you call this (with a different
         reference), a superscript 2 is inserted.
  
      2) This function returns HTML. It is meant to be used inside a Markdown cell in your IPython
         notebook, or concatenated together with another string that's used as input to a function
         here in the `report` module.
  
      Examples
      --------
      You want to insert a reference at the current position, and store it using a short label so you
      can access it again without typing the entire reference text.
  
          >>> reference('Roo, et al. "How to Python." Nature, 2019.', 'roo1')
          '<sup class="reference">1</sup>'
  
      The next time you want to insert this reference, just use the short 'roo1' label.
  
          >>> reference(label='roo1')
          '<sup class="reference">1</sup>'
  
      You want to insert a list of references in a single IPython cell, each with a short label, and
      use them all later without displaying any of the superscript reference numbers now.
  
          _ = reference('Roo, et al. "How to Python." Nature, 2019.', 'roo1')
          _ = reference('Roo, et al. "The Tao of Roo." Random House, 2018.', 'roo2')
          _ = reference('Roo, et al. "Roo and the Art of Database Maintenance." N/A, 2017.', 'roo3')
  
          ~~~ And later, in a Markdown cell in your IPython notebook ~~~
  
          As Roo, et al. outlined in a previous work{reference(label='roo2')}, all play and no work
          makes for a happy dog. Later, the same authors applied similar reasoning to the care of
          Burmese Pythons{reference(label='roo1')}. By comparing the care of dogs and Pythons to
          SQL databases, Roo, et al. make a compelling argument for why writing docstrings can be fun
          and not just a chore{reference(label='roo3')}.
  
      You want to insert a reference into a figure legend, using `report.legend`.
  
          report.legend(
              'As you can clearly see in the above figure, the data supports my conclusion '
              'and does not support the conclusion of my peers{reference(label='similar_paper1')}. '
              'This is most likely because I am smarter and more attractive than the authors of '
              'those other publications{reference(label='ego_and_insecurity1')}.'
          )
      """
      if text is None and label is None:
          raise OneCodexException("Please specify at least one of: text, label")
  
      try:
          ipy = get_ipython()
          ref_list = ipy.meta.get("references", {})
      except NameError:
          raise OneCodexException("Must be run from within IPython")
  
      def to_html(ref_num):
          return '<sup class="reference">{}</sup>'.format(ref_num)
  
      if text is not None:
          # has this reference already been cited?
          for ref_label, (ref_num, ref_text) in ref_list.items():
              if text == ref_text:
                  if label is not None and label != ref_label:
                      raise OneCodexException(
                          "Citation already in use with label={}".format(ref_label)
                      )
                  else:
                      break
          else:
              # reference has not been cited. is the label already in use?
              if label is not None and label in ref_list.keys():
                  raise OneCodexException("Citation label={} already in use".format(label))
  
              # create the citation and assign next number
              if not ref_list:
                  ref_num = 1
              else:
                  ref_num = max([x[0] for x in ref_list.values()]) + 1
  
              if label is None:
                  ref_label = ref_num
              else:
                  ref_label = label
  
              ref_list[ref_label] = (ref_num, text)
              ipy.meta["references"] = ref_list
  
          return to_html(ref_num)
      elif label is not None:
          if label not in ref_list.keys():
              raise OneCodexException("Cannot find citation with label={}".format(label))
  
          return to_html(ref_list[label][0])