在flashlight-Cpu V0.3.2 通过 Doxygen+sphinx 生成技术文档的完整教程及踩的坑解决方法

测试通过的操作系统环境：

Ubuntu Linux 20.04 LTS
系统内核：Linux ubuntu 5.15.0-46

第一步首先安装 Doxygen：

我们安装Doxygen有两种方式 一种是官方下载源代码编译安装，第二种是从官方下载已编译过的Linux二进制安装包。
本次实验我们采用从官方直接下载二进制软件包方式：
目前最新版本是：doxygen-1.9.5.linux.bin.tar.gz
下载地址：https://www.doxygen.nl/files/doxygen-1.9.5.linux.bin.tar.gz

#进入下载目录
cd /root/Downloads #因为我用了root 账号所以浏览器默认下载地址是 /root/Downloads
#解压doxygen-1.9.5.linux.bin.tar.gz压缩文件
tar -zxvf doxygen-1.9.5.linux.bin.tar.gz # 在/root/Downloads目下执行
#进入解压目录
cd doxygen-1.9.5 #进去后当前目录应该是 /root/Downloads/doxygen-1.9.5/
#执行make install 安装软件
make install

软件默认安装目录是 /usr/local/bin， 安装完成后我们通过查看版本方式验证以下：

# 查看版本命令
doxygen -v

# 如果安装成功了终端测试结果如下：
root@yark-Ai:~# doxygen -v
1.9.5 (2f6875a5ca481a69a6f32650c77a667f87d25e88)
root@yark-Ai:~# 

第二步我们来安装:

sphinx2.0.1
breathe4.13
sphinx_rtd_theme

具体安装方法如下，首先我们要进入flashlight的docs目录

cd /root/mytools/flashlight/docs #这是我的flashlight目录,大家要进自己下载的flashlight/docs目录

#通过pip来安装相关依赖，我这里默认为大家已安装了python和pip，如果没有大家可以参考我的“部署flashlight环境”的文档
pip install -r requirements.txt

安装成功了，大家继续下一步，如果网络原因下载失败某些依赖出错大家不要慌，重复执行执行这个命令，直到所有依赖下载完毕到安装成功。

第三步通过Doxygen生成技术文档：

在docs目录执行下面的命令生成html文件：

doxygen && make html

如果安装成功了，大家可以下一步， 很遗憾这一步骤大家基本踩坑，生成过程中会提示错误：
Running Sphinx v2.0.1 Extension error:

Running Sphinx v2.0.1
Extension error:
Could not import extension sphinx.builders.latex (exception: cannot import name 'contextfunction' from 'jinja2' (/usr/local/lib/python3.8/dist-packages/jinja2/__init__.py))
make: *** [Makefile:19: html] Error 2

第四步错误分析及解决方法：

错误提示是，Sphinx从jinja2中无法调入扩展sphinx.builders.latex
根本原因是，Sphinx v2.0.1和当前jinja2(pip安装Sphinx时候默认安装出来的jinja2 v3.1.2 )的版本不兼容，
我从官方安装多个版测试后最后发现jinja2 v3.1及以上版本和Sphinx v2.0.1不兼容法会出现此类错误，我从官方用pip 指定版本的方式了安装了jinja2 v3.0.3

#我们首先卸载已安装的jinja2
pip uninstall jinja2 #我这里用了root账号 所以忽略了加 sudo
#卸载成功后，安装我们指定版的jinja2
pip install jinja2==3.0.3
#安装完毕后，我们查看以下 jinja2版本
pip list | grep Jinja

#查看版本结果如下:
root@yark-Ai:~/mytools/flashlight/docs# pip list | grep Jinja
Jinja2                        3.0.3
root@yark-Ai:~/mytools/flashlight/docs#

安装成功了，我们再次执行 第三步 ,如果前面第三步没出错，就忽略这些。

第五步技术文档本地查看：

我们可以通过python的 web服务模块来在本地浏览访问，flashlight/docs/build/html下面的技术文档
本地网址：http://localhost:3288/

#查看技术文档，我们将在docs/build/html 里面启用http web 服务
#进入 docs/build/html
cd html
root@yark-Ai:~/mytools/flashlight/docs/build/html  #python -m http.server 3288   #我没有其他web 服务，刚好python 自带直接用了
# 端口号大家自己选就行了 我这里用了 3288

第六步我们在浏览器查看我们自己搭建的技术文档服务

python -m http.server 3288 执行这个后终端别关闭，不然web服务会停止，大家可以部署到自己别的本地web服务器上。
我们浏览器上的效果如下：

提示：

如果以上画面恭喜您！，您已经生成及部署完成本地技术文档！