Automatic :noindex: for sub-objects

[outkine]

In my documentation, I list an abridged version of several previously-defined classes. In order to prevent duplicate indexing, I assumed that I would only need one :noindex: for each:

.. class:: State
    :noindex:

    .. attribute:: turn_num
    .. attribute:: our_team
    .. method:: obj_by_coords(coords)

.. class:: Obj
    :noindex:

    .. attribute:: id
    .. attribute:: coords
    .. attribute:: obj_type

...but this produces warnings:

WARNING: duplicate object description of State.our_team, other instance in api, use :noindex: for one of them
WARNING: duplicate object description of State.obj_by_coords, other instance in api, use :noindex: for one of them
etc

The solution is very verbose:

.. class:: State
    :noindex:

    .. attribute:: turn_num
        :noindex:
    .. attribute:: our_team
        :noindex:
    .. method:: obj_by_coords(coords)
        :noindex:

.. class:: Obj
    :noindex:

    .. attribute:: id
        :noindex:
    .. attribute:: coords
        :noindex:
    .. attribute:: obj_type
        :noindex:

It seems to me like it would always make sense to automatically apply :noindex: to all the children of a parent with :noindex:. Am I missing something?

[jakobandersen]

I completely agree that noindex should apply recursively, and even label this a bug. Depending on the domain it may not even be possible to not apply it recursively (see #7052 for some related discussion on noindex).

[tk0miya]

I guess it is designed to put a class definition to multiple documents or sections. For example, python-doc describes object class in multiple sections:
https://docs.python.org/3/reference/datamodel.html#basic-customization
https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access
https://docs.python.org/3/reference/datamodel.html#implementing-descriptors

[outkine]

@tk0miya That makes sense, but my use case is slightly different. I have an "API" page with the complete list of classes and methods, and then I display an abridged version of those classes on the "Getting Started" page. So, in a way, I'm using :noindex: as a way of "quoting" objects defined elsewhere. Not sure if there is a better solution for this.

[jakobandersen]

@tk0miya That makes sense, but my use case is slightly different. I have an "API" page with the complete list of classes and methods, and then I display an abridged version of those classes on the "Getting Started" page. So, in a way, I'm using :noindex: as a way of "quoting" objects defined elsewhere. Not sure if there is a better solution for this.

I suggest adding an alias directive, similar to those for the C++ (and as of a few minutes ago, also the C) domain. It is meant exactly for this purpose.
I'm not familiar with the internals of the Python domain, but one implementation route is:

• In add_target_and_index, save signatures in the domain data so it is a available for xref lookups.
• Splice out the signature-to-node generation from handle_signature so it can be utilized elsewere.
• Add the new directive which basically takes a list of names as argument (names in the same way as those given as a xref).
• In the post-transform for the alias directive, look up the xrefs and replace them with the signature. Here the name in the signature should be a pending_xref to the actual declaration, instead of the usual add_name.