Add option :hidden: to ObjectDescription.  Currently, this option has no
effect except being stored as attribute in the resulting node.

Do not produce any output only a target node if option :hidden: is
given.  In this case all nodes representing this ObjectDescription are
replaced by a single target where the target gets assigned all ids of
the replaced nodes.

Record the source information (class attributes source and line) when
replacing an object description node with a target node.

The collect_ids() function uses the its second parameter ``ids:
List[str]`` as in- and output parameter and always returns None.
Rewrite the function to become pure and side effect free: return the
list of ids as the return value not as an output parameter.

replace_node_with_target() does not access the self-instance.  Thus,
declare it as a static method.

Move the collect_ids() method from inside the replace_node_with_target()
into the class scope (as static method) since it does not need the
closure of the surrounding replace_node_with_target() method.  This also
gives a potential speed boost.

Inline the one-line method replace_node_with_target() into its only call
site.  Since there are no call sites left, remove the method afterwards.

Instead of overriding the `option_spec` variable copy the `option_spec`
of the superclass and update it.  This way changes in the superclass
propagate to its children.  This is in line how other classes use
"`option_spec`-inheritance".

The alias objects override the run() method and thus do not support
``:notypesetting:`` option.

Correct node order generated by the .. js:module:: directive:  When
generating an index entry, the index node must come before the target
node.

Correct node order generated by the .. py:module:: directive:  When
generating an index entry, the index node must come before the target
node.

It might be that a object description has no ids associated with it,
e.g. if the option :noindex: is passed.  In this case we would replace
the object description node with a target node, which has no ids.  This
breaks docutils assumption about a target node and leads not errors.
Therefore, do only create a target node if we have ids to work with.

An index directive creates a index node followed by a target node.  Two
consecutive index directives::

.. index:: first
.. index:: second

create index, target, index, target, i.e. a mixture.  The interspersed
index nodes prevent other transformations, e.g. PropagateTargets to
properly work on the target nodes.

Apply a transformation which reorders mixed and consecutive index and
target nodes such that first all index nodes are before all target
nodes:

Given the following document as input:

    <document>
        <target ids="id1" ...>
        <index entries="...1...">
        <target ids="id2" ...>
        <target ids="id3" ...>
        <index entries="...2...">
        <target ids="id4" ...>

The transformed result will be:

    <document>
        <index entries="...1...">
        <index entries="...2...">
        <target ids="id1" ...>
        <target ids="id2" ...>
        <target ids="id3" ...>
        <target ids="id4" ...>

The post transform ReorderConsecutiveTargetAndIndexNodes reorders index
and target nodes.  A snipped like::

   .. py:module:: mymodule
   .. py:data:: myvar

generates the nodes::

   <index mymodule>
   <target mymodule>
   <index myvar>
   <descr myvar>

which get reordered to::

   <index mymodule>
   <index myvar>
   <target mymodule>
   <descr myvar>

# Conflicts:
#	doc/usage/restructuredtext/domains.rst
#	sphinx/directives/__init__.py
#	sphinx/domains/c.py
#	sphinx/domains/cpp.py
#	sphinx/domains/javascript.py
#	sphinx/domains/python.py
#	sphinx/transforms/__init__.py