Fix nested groups and global class output

README.md

@@ -67,8 +67,9 @@ Moxygen supports both of the common Doxygen documentation styles:
 1. Explicit grouped compounds.
    - `@defgroup`, `@ingroup`, and related tags produce normal Doxygen group XML.
    - Moxygen renders those groups directly.
+   - The root `api.md` page lists top-level groups before classes, and nested group pages list their child groups with breadcrumbs.
 2. File-level grouped code.
-   - Some codebases group files with `@addtogroup` / `@ingroup`, but Doxygen emits sparse group XML and leaves the real compound ownership in file XML.
+   - Some codebases group files with `@addtogroup` blocks or `@file` comments with `@ingroup`, but Doxygen emits sparse group XML and leaves the real compound ownership in file XML.
    - Moxygen can recover those grouped classes, namespaces, and members when you pass `--source-root`.
    - Shared umbrella namespaces across multiple groups are preserved without dropping group-owned root classes, and cross-page refs are resolved correctly for both markdown mirrors and generated multi-page output.
 
@@ -95,6 +96,8 @@ Multi-file grouped output:
 moxygen --anchors --groups --output api-%s.md /path/to/doxygen/xml
 ```
 
+Grouped output writes group files such as `api-mygroup.md` plus `api.md` for root-level globals and the top-level group/class index, unless `--noindex` is set.
+
 Grouped output recovered from file-level grouping comments:
 ```
 moxygen --anchors --groups --source-root /path/to/project/src \
@@ -106,6 +109,8 @@ Per-class files:
 moxygen --classes --output api-%s.md /path/to/doxygen/xml
 ```
 
+Per-class output writes class files plus `api.md` for root-level globals and the class/namespace index, unless `--noindex` is set.
+
 Java project:
 ```
 moxygen --language java --anchors /path/to/doxygen/xml

docs/cli-reference.md

@@ -26,3 +26,5 @@ moxygen [options] <doxygen XML directory>
 | `-f, --frontmatter` | Prepend YAML frontmatter to output files |
 | `-L, --logfile [file]` | Output log messages to file |
 | `-q, --quiet` | Quiet mode |
+
+When `--groups` or `--classes` is enabled, Moxygen writes the split files and also writes `api.md` for root-level globals and the top-level index unless `--noindex` is set.

docs/grouping-modes.md

@@ -15,9 +15,11 @@ Use `@defgroup`, `@ingroup`, and related tags. Doxygen produces normal group XML
 moxygen --groups --output api-%s.md /path/to/xml
 ```
 
+The root `api.md` page lists top-level groups before classes. Group pages list nested groups before classes and include breadcrumbs back to their parent groups.
+
 ## File-level grouped code
 
-Some codebases group files with `@addtogroup` / `@ingroup`, but Doxygen emits sparse group XML and leaves the real compound ownership in file XML.
+Some codebases group files with `@addtogroup` blocks or `@file` comments with `@ingroup`, but Doxygen emits sparse group XML and leaves the real compound ownership in file XML.
 
 Moxygen recovers those grouped classes, namespaces, and members when you pass `--source-root`:
 

docs/writing-doxygen.md

@@ -28,7 +28,7 @@ If you want private members in the generated Markdown, Doxygen must emit them fi
 EXTRACT_PRIVATE = YES
 ```
 
-For grouped output, keep the XML directory and source tree relationship clear. If Doxygen emits sparse group XML for file-level `@addtogroup` or `@ingroup` comments, pass `--source-root` so Moxygen can inspect the source comments that Doxygen left out of the group compound XML.
+For grouped output, keep the XML directory and source tree relationship clear. If Doxygen emits sparse group XML for file-level `@addtogroup` blocks or `@file` comments with `@ingroup`, pass `--source-root` so Moxygen can inspect the source comments that Doxygen left out of the group compound XML.
 
 ```bash
 moxygen --groups \

example/doc/api-bicycle.md

@@ -1,59 +1,106 @@
-# bicycle {#group__bicycle}
+{#byciclemodule}
+
+# Bycicle module
 
 Bicycle module contains the bicycle class. Bicycles are a useful way of transporting oneself, without too much effort.
 
 ### Classes
 
 | Name | Description |
 |------|-------------|
-| [`Bicycle`](#classtransport_1_1Bicycle) | Standard bicycle class. |
+| [`Bicycle`](#bicycle) | Standard bicycle class. |
+
+{#bicycle}
 
-## Bicycle {#classtransport_1_1Bicycle}
+## Bicycle
 
-> **Subclasses:** `transport::MountainBike`, `transport::RacingBike`
-> **Defined in:** `bicycle.h`
+```cpp
+#include <bicycle.h>
+```
+
+```cpp
+class Bicycle
+```
+
+Defined in src/bicycle.h:17
+
+> **Subclassed by:** [`MountainBike`](api-mountainbike.md#mountainbike), [`RacingBike`](api-racingbike.md#racingbike)
 
 Standard bicycle class.
 
-[Bicycle](#classtransport_1_1Bicycle) implements a standard bicycle. Bicycles are a useful way of transporting oneself, without too much effort (unless you go uphill or against the wind). If there are a lot of people on the road, you can use `RingBell` to ring your bell (**note**, not all bicycles have bells!).
+[Bicycle](#bicycle) implements a standard bicycle. Bicycles are a useful way of transporting oneself, without too much effort (unless you go uphill or against the wind). If there are a lot of people on the road, you can use `RingBell` to ring your bell (**note**, not all bicycles have bells!).
 
-### Members
+### List of all members
 
-| Name | Description |
-|------|-------------|
-| [`PedalHarder`](#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef) | PedalHarder makes you go faster (usually). |
-| [`RingBell`](#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b) | Ring bell on the bike. |
-| [`~Bicycle`](#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25) | Default destructor. |
+| Name | Kind | Owner |
+|------|------|-------|
+| [`PedalHarder`](#pedalharder) | `function` | Declared here |
+| [`RingBell`](#ringbell) | `function` | Declared here |
+| [`~Bicycle`](#bicycle-1) | `function` | Declared here |
+
+### Public Methods
+
+| Return | Name | Description |
+|--------|------|-------------|
+| `void` | [`PedalHarder`](#pedalharder) `virtual` | PedalHarder makes you go faster (usually). |
+| `void` | [`RingBell`](#ringbell) `virtual` | Ring bell on the bike. |
+|  | [`~Bicycle`](#bicycle-1) `virtual` | Default destructor. |
 
 ---
 
-#### PedalHarder {#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef}
+{#pedalharder}
+
+#### PedalHarder
+
+`virtual`
 
 ```cpp
 virtual void PedalHarder()
 ```
 
+Defined in src/bicycle.h:20
+
 PedalHarder makes you go faster (usually).
 
+##### Reimplemented by
+
+- [`PedalHarder`](api-racingbike.md#pedalharder-1)
+
 ---
 
-#### RingBell {#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b}
+{#ringbell}
+
+#### RingBell
+
+`virtual`
 
 ```cpp
 virtual void RingBell()
 ```
 
+Defined in src/bicycle.h:27
+
 Ring bell on the bike.
 
 RingBell rings the bell on the bike. Note that not all bikes have bells.
 
+##### Reimplemented by
+
+- [`RingBell`](api-racingbike.md#ringbell-1)
+
 ---
 
-#### ~Bicycle {#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25}
+{#bicycle-1}
+
+#### ~Bicycle
+
+`virtual`
 
 ```cpp
 virtual ~Bicycle()
 ```
 
+Defined in src/bicycle.h:30
+
 Default destructor.
 

example/doc/api-mountainbike.md

@@ -1,64 +1,97 @@
-# mountainbike {#group__mountainbike}
+{#mountainbikemodule}
+
+# Mountain bike module
 
 Mountain bike module contains the `MountainBike` class. Mountain bikes are a kind of bike for cycling on rough terrain.
 
 ### Classes
 
 | Name | Description |
 |------|-------------|
-| [`MountainBike`](#classtransport_1_1MountainBike) | Mountain bike implementation of a `[Bicycle](example/doc/api-bicycle.md#classtransport_1_1Bicycle)`. |
+| [`MountainBike`](#mountainbike) | Mountain bike implementation of a `[Bicycle](api-bicycle.md#bicycle)`. |
 
-## MountainBike {#classtransport_1_1MountainBike}
+{#mountainbike}
 
-> **Extends:** `transport::Bicycle`
-> **Defined in:** `mountainbike.h`
+## MountainBike
 
-Mountain bike implementation of a `[Bicycle](example/doc/api-bicycle.md#classtransport_1_1Bicycle)`.
+```cpp
+#include <mountainbike.h>
+```
 
-[MountainBike](#classtransport_1_1MountainBike) is an implementation of a [Bicycle](example/doc/api-bicycle.md#classtransport_1_1Bicycle) providing a bike for cycling on rough terrain. Mountain bikes are pretty cool because they have stuff like **Suspension** (and you can even adjust it using SetSuspension). If you're looking for a bike for use on the road, you might be better off using a [RacingBike](example/doc/api-racingbike.md#classtransport_1_1RacingBike) though.
+```cpp
+class MountainBike
+```
 
-### Members
+Defined in src/mountainbike.h:20
 
-| Name | Description |
-|------|-------------|
-| [`SetSuspension`](#classtransport_1_1MountainBike_1a04caecd7e5ff7572b6ac1dc283510301) | Set suspension stiffness.  the suspension stiffness. |
-| [`ChangeBreak`](#classtransport_1_1MountainBike_1afd02513876a196e98acaacdc555aeb52) | Change the break type.  the break type.  the type of the break. |
+> **Inherits:** [`Bicycle`](api-bicycle.md#bicycle)
+
+Mountain bike implementation of a `[Bicycle](api-bicycle.md#bicycle)`.
+
+[MountainBike](#mountainbike) is an implementation of a [Bicycle](api-bicycle.md#bicycle) providing a bike for cycling on rough terrain. Mountain bikes are pretty cool because they have stuff like **Suspension** (and you can even adjust it using SetSuspension). If you're looking for a bike for use on the road, you might be better off using a [RacingBike](api-racingbike.md#racingbike) though.
+
+### List of all members
+
+| Name | Kind | Owner |
+|------|------|-------|
+| [`SetSuspension`](#setsuspension) | `function` | Declared here |
+| [`ChangeBreak`](#changebreak) | `function` | Declared here |
+| [`PedalHarder`](api-bicycle.md#pedalharder) | `function` | Inherited from [`Bicycle`](api-bicycle.md#bicycle) |
+| [`RingBell`](api-bicycle.md#ringbell) | `function` | Inherited from [`Bicycle`](api-bicycle.md#bicycle) |
+| [`~Bicycle`](api-bicycle.md#bicycle-1) | `function` | Inherited from [`Bicycle`](api-bicycle.md#bicycle) |
+
+### Inherited from [`Bicycle`](api-bicycle.md#bicycle)
+
+| Kind | Name | Description |
+|------|------|-------------|
+| `function` | [`PedalHarder`](api-bicycle.md#pedalharder) `virtual` | PedalHarder makes you go faster (usually). |
+| `function` | [`RingBell`](api-bicycle.md#ringbell) `virtual` | Ring bell on the bike. |
+| `function` | [`~Bicycle`](api-bicycle.md#bicycle-1) `virtual` | Default destructor. |
+
+### Public Methods
+
+| Return | Name | Description |
+|--------|------|-------------|
+| `bool` | [`SetSuspension`](#setsuspension)  | Set suspension stiffness. the suspension stiffness. |
+| `bool` | [`ChangeBreak`](#changebreak) `inline` | Change the break type. the break type. the type of the break. |
 
 ---
 
-#### SetSuspension {#classtransport_1_1MountainBike_1a04caecd7e5ff7572b6ac1dc283510301}
+{#setsuspension}
+
+#### SetSuspension
 
 ```cpp
 bool SetSuspension(double stiffness)
 ```
 
+Defined in src/mountainbike.h:32
+
 Set suspension stiffness.  the suspension stiffness.
 
 SetSuspension changes the stiffness of the suspension on the bike. The method will return false if the stiffness could not be adjusted.
 
 #### Returns
 true if the suspension was adjusted successfully, false otherwise.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `stiffness` | `double` |  |
-
 ---
 
-#### ChangeBreak {#classtransport_1_1MountainBike_1afd02513876a196e98acaacdc555aeb52}
+{#changebreak}
+
+#### ChangeBreak
+
+`inline`
 
 ```cpp
 template<typename BreakType> inline bool ChangeBreak(BreakType breakType)
 ```
 
+Defined in src/mountainbike.h:46
+
 Change the break type.  the break type.  the type of the break.
 
 ChangesBreak changes the type of break fitted to the bike. The method will return false if the break type could not be fitted.
 
 #### Returns
 true if the break was adjusted successfully. false otherise
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `breakType` | `BreakType` |  |
-