Doxygen 1.8.17在Ubuntu 20.04生成HTML时treeview不显示如何解决？

问题背景 #

使用完全相同的Doxyfile配置，在Windows 10与Ubuntu 20.04上通过Doxygen 1.8.17生成HTML格式文档时，Ubuntu环境生成的index.html没有显示树视图（treeview），无法通过树视图实现页面跳转。

参考配置（与默认Doxygen 1.8.17的差异项） #

# Difference with default Doxyfile 1.8.17
PROJECT_NAME           = PROJECT
PROJECT_NUMBER         = v050051
PROJECT_BRIEF          = "Test"
PROJECT_LOGO           = ./logo.png
OUTPUT_DIRECTORY       = .
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_ALL            = YES
CASE_SENSE_NAMES       = NO
HIDE_SCOPE_NAMES       = YES
INPUT                  = . \
                         ../../common/api.h
FILE_PATTERNS          = *.c \
                         *.cc \
                         *.cxx \
                         *.cpp \
                         *.c++ \
                         *.java \
                         *.ii \
                         *.ixx \
                         *.ipp \
                         *.i++ \
                         *.inl \
                         *.idl \
                         *.ddl \
                         *.odl \
                         *.h \
                         *.hh \
                         *.hxx \
                         *.hpp \
                         *.h++ \
                         *.l \
                         *.cs \
                         *.d \
                         *.php \
                         *.php4 \
                         *.php5 \
                         *.phtml \
                         *.inc \
                         *.m \
                         *.markdown \
                         *.md \
                         *.mm \
                         *.dox \
                         *.py \
                         *.pyw \
                         *.f90 \
                         *.f95 \
                         *.f03 \
                         *.f08 \
                         *.f18 \
                         *.f \
                         *.for \
                         *.vhd \
                         *.vhdl \
                         *.ucf \
                         *.qsf \
                         *.ice
RECURSIVE              = YES
EXAMPLE_PATH           = ../../tools/test.c
EXAMPLE_RECURSIVE      = YES
SOURCE_BROWSER         = YES
DISABLE_INDEX          = YES
GENERATE_TREEVIEW      = YES
MATHJAX_RELPATH        =
GENERATE_LATEX         = NO
GENERATE_XML           = YES
CLASS_DIAGRAMS         = NO
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

运行日志差异 #

解决步骤 #

按照优先级依次尝试以下操作：

• 优先重新安装完整版本的Doxygen：部分精简安装的Ubuntu环境下的Doxygen缺失动态树视图生成所需的组件，执行以下命令重装即可：

sudo apt update
sudo apt reinstall doxygen

• 调整大小写敏感配置：你当前配置CASE_SENSE_NAMES = NO，但Ubuntu系统本身是文件大小写敏感的，如果源码路径存在大小写混写的情况，会导致Doxygen扫描文件不全，无法生成完整的树视图索引。将该配置项改为YES后重新生成文档测试。
• 检查输出目录权限：确保运行Doxygen的用户对OUTPUT_DIRECTORY指定的目录有读写权限，树视图依赖的navtree*.js类索引文件如果写入失败，就会出现页面无树视图的问题。
• 浏览器端排查：打开生成的index.html后按F12调出开发者控制台，查看是否有JS报错或者静态资源404的情况。如果提示jquery相关报错，可以手动将对应版本的jquery文件放入HTML输出目录的jquery.js路径，或者在Doxyfile中补充HTML_EXTRA_FILES配置引入本地jquery文件。

内容的提问来源于stack exchange，提问作者Kenny Pan