Skip to content

Fix empty navigation tree in doxygen documentation output#1349

Merged
AniruddhaKanhere merged 1 commit into
FreeRTOS:mainfrom
AniruddhaKanhere:fix/doxygen-navtree-empty
Jun 18, 2026
Merged

Fix empty navigation tree in doxygen documentation output#1349
AniruddhaKanhere merged 1 commit into
FreeRTOS:mainfrom
AniruddhaKanhere:fix/doxygen-navtree-empty

Conversation

@AniruddhaKanhere

Copy link
Copy Markdown
Member

Description

The published API documentation at https://freertos.github.io/FreeRTOS-Plus-TCP/ renders pages but has an empty navigation tree — none of the documented files, types, or functions are reachable from the UI. The generated navtreedata.js contains only the (empty) main page:

var NAVTREE = [ [ "FreeRTOS-Plus-TCP", "index.html", ] ];

Root cause

docs/doxygen/layout.xml was authored for doxygen 1.8.20, where wrapping a visible <filelist> tab inside a <tab type="files" visible="no"> parent was the idiom to show a single flat "Files" entry. In doxygen 1.9.x and later, an invisible parent tab hides its entire subtree, so the file list never renders. Because classes/structs and globals are intentionally hidden in this layout, the file list is the only navigable content — hiding it leaves the navigation effectively empty.

Fix

Set the parent files tab to visible="yes". The file list renders again; globals and internal data structures remain hidden, preserving the original layout intent.

-    <tab type="files" visible="no" title="">
+    <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="Files" .../>
       <tab type="globals" visible="no" title="" intro=""/>
     </tab>

Test Steps

  • Reproduced the empty navtree locally from the current config.doxyfile (doxygen 1.16.1) — matches the live site.
  • After the change, a clean rebuild (doxygen docs/doxygen/config.doxyfile, exit 0, no new warnings) produces a populated navtree (Files → all 42 documented source files), and API functions such as FreeRTOS_socket are reachable.

Note

Already-deployed per-version sites on the gh-pages branch will remain broken until regenerated and redeployed; this change fixes future doxygen builds.

The custom docs/doxygen/layout.xml (authored for doxygen 1.8.20) wraps a
visible <filelist> tab inside a <tab type="files" visible="no"> parent.
In doxygen 1.9.x and later, an invisible parent tab hides its entire subtree,
so the file list never renders. Since classes/structs and globals are hidden
by design, the file list is the only navigable content, leaving the published
docs at https://freertos.github.io/FreeRTOS-Plus-TCP/ with an effectively
empty navigation tree and unreachable API documentation.

Set the parent 'files' tab to visible="yes" so the file list renders again.
Globals and internal data structures remain hidden, preserving the original
layout intent.
@AniruddhaKanhere AniruddhaKanhere enabled auto-merge (squash) June 18, 2026 23:36
@AniruddhaKanhere AniruddhaKanhere merged commit 4f674b3 into FreeRTOS:main Jun 18, 2026
18 of 20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants