Doxygen 可以用于代码API与文档的导出,格式是html格式,能在网页端直接浏览

优点:
拓展性高
操作简单
支持MarkDown
一键导出静态网页
缺点:
界面古董(可解决)
代码注释格式严格(可配置)

最终效果

image.png

使用教程:

安装doxygen: https://www.doxygen.nl/download.html

我通常在项目下面建立一个doxygen文件夹,然后关于文档的东西都放里面

打开doxygen,填写信息:

• 填写一下Project信息,此时我们保存一下Doxygen,Ctrl + S即可,图中的 Doxyfile 就是这么来的, 这一步很重要
  

  image.png

• Mode信息,选一下你要导出什么语言的

image.png

• 运行并生成

image.png

• 此时即可查看到,你生成的网页了,Classes里面还包含了你的代码的API内容,前提是你弄好了注释内容

image.png

---

进阶

上面我们告诉了你怎么生成一个最简单的doxygen网页api模板,接下就是修改版面内容与调整样式了

自定义多标签页

来到你的安装目录 .../doxygen/bin .找到 doxygen.exe ,我装在C盘位置如图:

image.png

管理员身份打开cmd,用命令行调用生成文件命令,将生成的4个文件复制到我们的工作目录

//去到doxygen.exe目录下
cd C:\Program Files\doxygen\bin

//生成DoxygenLayout.xml文件
doxygen.exe -l

//生成 header.html footer.html stylesheet.css 三个文件
doxygen.exe -w html header.html footer.html stylesheet.css

此时我们在 .../project/doxygen/ 下的目录应该是这样的,下面开始配置进去

Doxyfile                //doxygen保存的工程文件
DoxygenLayout.xml       //用于配置多个标签页分布的xml
footer.html             //用于后续改好看样式的文件
header.html             //用于后续改好看样式的文件
stylesheet.css          //用于后续改好看样式的文件
md / main.md            //主页面使用的markdown
md / quickstart.md      //快速开始页面使用的markdown

• 打开 DoxygenLayout.xml文件,添加一行

<tab type="mainpage" visible="yes" title=""/>
<!-- 添加一行选项  使用方法,统一格式:md_{filepath}.html  (md_代表markdown文件,后面开始就是文件路径md_quickstart) -->
<tab type="user" visible="yes" url="md_md_quickstart.html" title="快速开始"/>
<!-- 最好注释掉下面这行 -->
<!-- <tab type="pages" visible="yes" title="" intro=""/> -->

• 回到我们的doxygen程序,配置以下内容

• Expert > Input > INPUT 把我们的md文件夹配置进去,上面那个是项目代码地址

image.png

• Expert > Input > USE_MDFILE_AS_MAINPAGE

image.png

• Expert > Build > LAYOUT_FILE

image.png

• 完成后Run一次再查看,就有主页内容与自定义的标签页了

image.png

下面开始讲样式调整

第三方的很精美的css库: https://github.com/jothepro/doxygen-awesome-css

• 下载下来,放在Doxfile同级目录,并把该文件加入到使用列表

image.png

• 修改以下属性

image.png image.png

docxygen-awesome上是用文本方式打开Doxyfile修改的,也可以.

# Doxyfile
GENERATE_TREEVIEW      = YES # optional. Also works without treeview
HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css

横线内是非必要内容

---

*黑暗模式(这个功能有时候不好使,就是黑暗模式)

image.png

footer.html 复制到相同位置

<!--END !GENERATE_TREEVIEW-->
<script type="text/javascript">
  $(document).ready(function(){
      toggleButton = document.createElement('doxygen-awesome-dark-mode-toggle')
      toggleButton.title = "Toggle Light/Dark Mode"
      document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
  })
</script>
</body>
</html>

header.html

---

$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
$extrastylesheet
</head>

• 保存后重新打开运行一下,最终效果,简直完美

image.png

使用doxygen style的自动注释(VS 2019才支持)

image.png

输入///即可自动提示注释内容

• PS,那个黑暗样式我到现在也没成功弄出来,有弄出来的可以告诉一下怎么搞的