Embeds a document inside this document.

        This method embeds the given document in this document with the given
        ``rel``. If one or more documents have already been embedded for that
        ``rel``, the new document will be embedded in addition to those
        documents.

        This method returns self, allowing it to be chained with additional
        method calls.

        Arguments:

        - ``rel``: a string specifying the link relationship type of the
          embedded resource. ``rel`` should be a well-known link relation name
          from the IANA registry
          (http://www.iana.org/assignments/link-relations/link-relations.xml),
          a full URI, or a CURIE.
        - ``target``: a ``Builder`` instance or a ``dougrain.Document``
          instance that will be embedded in this document.
        - ``wrap``: Defaults to False, but if True, specifies that the embedded
          resource object should be initally wrapped in a JSON array even if it
          is the first embedded resource for the given ``rel``.

        Unlike ``dougrain.Document.embed``, this method does not detect
        equivalence between relationship types with different representations.

        WARNING: ``target`` should not be identical to ``self`` or any document
        that embeds ``self``.

def embed(self, rel, target, wrap=False):
        """Embeds a document inside this document.

        This method embeds the given document in this document with the given
        ``rel``. If one or more documents have already been embedded for that
        ``rel``, the new document will be embedded in addition to those
        documents.

        This method returns self, allowing it to be chained with additional
        method calls.

        Arguments:

        - ``rel``: a string specifying the link relationship type of the
          embedded resource. ``rel`` should be a well-known link relation name
          from the IANA registry
          (http://www.iana.org/assignments/link-relations/link-relations.xml),
          a full URI, or a CURIE.
        - ``target``: a ``Builder`` instance or a ``dougrain.Document``
          instance that will be embedded in this document.
        - ``wrap``: Defaults to False, but if True, specifies that the embedded
          resource object should be initally wrapped in a JSON array even if it
          is the first embedded resource for the given ``rel``.

        Unlike ``dougrain.Document.embed``, this method does not detect
        equivalence between relationship types with different representations.

        WARNING: ``target`` should not be identical to ``self`` or any document
        that embeds ``self``.
        """
        new_embed = target.as_object()
        self._add_rel('_embedded', rel, new_embed, wrap)

        if self.draft.automatic_link:
            self.add_link(rel, target, wrap)

        return self