Support docutils-0.18: Consume iterator of Element.traverse()

[tk0miya]

Feature or Bugfix

• Refactoring

Purpose

• Since 0.18, Element.traverse() returns an iterator instead of
  intermediate object. As a result, the return value is always considered
  as truthy value. And it becomes fragile when the caller modifies the
  doctree on the loop.
• refs: Update Sphinx to work with docutils-0.18.x #9777

[gmilde]

The reason for returning an iterator instead of a list is a considerable speedup in the majority of use cases. https://sourceforge.net/p/docutils/patches/160/
Be carful not to waste this gain by wrapping the return value in a list unless required.

If I get this right,

        doc = tree.traverse(nodes.document)[0]

just wants the first element that is of type "nodes.document".
Instead of traversing the complete tree, building a list of "document" nodes and picking the first

        doc = list(tree.traverse(nodes.document))[0]

one could use the iterators "next()" method:

        doc = tree.traverse(nodes.document).next()

(In cases where no matching node exists, the error returned would be
StopIteration instead of IndexError.)

or even simpler the next_node() method:

        doc = tree.next_node(nodes.document).next()

which returns the first matching node or None. (Note the different default of the optional argument "include_self".)