[multi-top] Documentation organization

Nobody has claimed this yet.

Our current documentation doesn't fully/ideally represent multiple top-level designs and their HW IP blocks yet. This issue describes the current status and the planned goal and tracks the open items to get there.

_Please note that this issue is only about documentation for the `master` branch and thus the current development version of tops and IPs. Documentation for other branches and releases is a separate issue, for which we're first awaiting SC guidance on releases._

## Top-level designs (tops)

Each top has its own section in the documentation; currently [Earlgrey](https://opentitan.org/book/hw/top_earlgrey/index.html) and [Darjeeling](https://opentitan.org/book/hw/top_darjeeling/index.html).

- [ ] Darjeeling's documentation (on `master`, which is what gets rendered) currently only consists of the datasheet. The remainder of the documentation (some of which already exists on the `multitop_dev` branch) needs to be added.

## Top-specific HW IPs

Top-specific HW IPs should be documented under the top they belong to, in the configuration used in that top. This is currently the case for some IPs (e.g., [`alert_handler`](https://opentitan.org/book/hw/top_earlgrey/ip_autogen/alert_handler/index.html)) but not for all (e.g., [`pwrmgr`](https://opentitan.org/book/hw/top_earlgrey/ip_autogen/pwrmgr/index.html)).

- [ ] Move/render the documentation of each top-specific IP in the top-specific section (and in the correct configuration).

As we tend to make more and more HW IPs templated in order to work around limitations of SystemVerilog parameters and generates, an open question is whether we should have a top-independent documentation section for those IPs and link top-specific instances from there. An important example is `rv_core_ibex`, which gets ipgen'd in #26083. Currently the 'generic' documentation for that HW IP links to the Earlgrey instance.

## Shared HW IPs

HW IPs shared between multiple tops (e.g., [`i2c`](https://opentitan.org/book/hw/ip/i2c/index.html)) should remain in the [Hardware IP Blocks](https://opentitan.org/book/hw/ip/index.html) section.

## Linking from a shared HW IP to a top-specific one

When linking from a shared HW IP to a top-specific one, we should inform the user about the top-specific variants of that IP (e.g., one for Darjeeling, another for Earlgrey) and link to them. These links ideally get auto-generated, so that doc writers can use a function (e.g., `{{ top_ip_links(pwrmgr) }}`) and the doc generator inserts links to all top-specific variants (based on the information about which top instantiates which IP). In the short term, it might be sufficient to link to one top-specific variant as an example.

- [ ] Evaluate complexity of auto-generated links to all top-specific variants.
- [ ] If complex, insert a link to one top-specific variant (as an example) as an intermediate solution. In that case, we also may have to evaluate an alternative long-term solution.
- [ ] Otherwise implement the auto-generated links to all top-specific IPs

Start by comparing the Darjeeling documentation on master with the existing material on the multitop_dev branch, then inspect the top-specific IP documentation linked in this issue. Determine the scope of moving or rendering top-specific IPs and whether shared-IP links need an automatic mechanism or an example link. Done means the listed documentation gaps and linking approach are resolved for master.

Written by the indexing model from the issue text.