Allow pages to be associated with a specific parent page, across qdoc projects.

Use Case

https://doc.qt.io/qt-6 features a left-side TOC that tries to semantically group pages into Overviews, Tools ... This works for pages that happen to be part of the 'top-level' qtdoc.git. Root pages from other modules can be placed into the structure, too, but there is no way to further organize the tree.

This leads to an unclear structure e.g. for Overviews. Some of the overviews are part of the 'top-level' qtdoc.qdocconf project, and appears under 'Overviews' . Other pages are - often for historic reasons - part of the documentation of individual Qt modules, and end up under this structure.

What we aim for is a way to reorganize the tree without moving lots of pages across repositories.

Related

qdoc already supports structuring of documentation that influences the TOC, but so far only inside a single documentation project:

\group / \ingroup

\group / \ingroup define a hierarchy. If a page that is not part of a toctitles hierarchy (see blow) uses \ingroup, and there is a \group page that's documented, then that is used as the parent page.

navigation.toctitles

navigation.toctitles can point to a page that contains a \list structure.

Ideas for implementation

\meta command

Allow to specify a parent page (that potentially lives outside of the current qdocconf project) inside the page.

For example, to show "The Meta Object System" page in QtCore as part of the global overview:

  \title The Meta Object System
  \meta{TocParent}{/Overviews}

This allows to redirect single pages without major changes.

Problematic is the 'magic' that we do this only for single pages, further complicating
the setup. Also, how should the child nodes be sorted?

Possible workaround for the latter: Add a placeholder node in the TOC where overview pages from non-qtdoc projects will be placed.

TOC Merging

Automatically 'merge' top-level topic pages with the same name. So if QtCore and QtDoc have an 'Overview' page, the children are merged:

Qt Core
+ Overviews
   + The Meta Object System
Qt Documentation
+ Overviews
   + All Overviews
   ...
   + Differences between String-Based and Functor-Based Connections

becomes

Qt Core
+ Overviews
   + The Meta Object System
Qt Documentation
+ Overviews
   + All Overviews
   ...
   + Differences between String-Based and Functor-Based Connections
   + The Meta Object System

This doesn't require any additions to qdoc language. But it will require somewhat pervasive changes over a lot of documentation projects / repositories, and opens the risk for typos etc. It also doesn't define how sub-nodes should be sorted, nor is it immediately clear which 'main' page would win for the top-level node.

Define TOC on page level

Follow the idea of Sphinx toctree::, and let the TOC be defined on page level:

\page overviews-main.html
\title Qt Overviews
// ...
\toc
    \tocentry {User Interfaces}{UI Frameworks}
    \tocentry {Desktop Integration}
    \tocentry {The Meta Object System}
    \tocentry {Networking and Connectivity}
    \tocentry {Inter-process communication in Qt}{IPC}
    ...
\endtoc

This allows to structure the TOC on page level. Sub-pages can in turn define their children.

This might also be a replacement for toc-titles, with the benefit of being more explicit. TODO: How does it relate to navigation.* in general?