关于Cmake-Cookbook书籍第12.3节无法使用基于python3的sphinx-build解决办法

---

问题点

---

在centos7环境下调试<<Cmake CookBook>>书籍第12章第3小节示例代码时,示例代码可以在< https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-12/recipe-03 >中找到,根据章节说明步骤结合Doxygen和Sphinx生成本小节html文档,当执行cmake --build . --target docs命令生成html格式说明文档时,报以下错误:

sphinx Could not import extension breathe (exception: No module named breathe)

本机环境已安装python3,和doxygen,且基于python3安装了sphinx和breathe,python2环境未安装breathe;

---

原因

经过排查,发现示例代码中的FindSphinx.cmake模块中采用以下方式查找sphinx-build构建命令:

find_program(SPHINX_EXECUTABLE NAMES sphinx-build
  HINTS
  $ENV{SPHINX_DIR}  # 环境变量SPHINX_DIR路径下查找
  HINTS ${SPHINX_ROOT}/bin  环境变量SPHINX_ROOT路径下的bin下查找
  PATH_SUFFIXES bin  # 以上两者未查找到,则在/bin目录下查找
  DOC "Sphinx documentation generator"
)

由于本机环境未设置指向sphinx-build路径所在的SPHINX_DIR和SPHINX_ROOT环境变量,导致当执行构建时默认找到/bin目录下的sphinx-build,而该sphinx-build是基于系统自带的python2环境下安装的sphinx,采用的是python2解析器,而不是python3环境下的sphinx-build,而python2环境未安装breathe库,所有当在sphinx的模板配置conf.py.in文件中设置extensions = ['breathe']时无法找到该扩展模块;

---

解决办法

• 确保按示例代码中程序的查找顺序,先查找python解析器,确保找到python解析器后再接着查找sphinx:

  find_package(PythonInterp REQUIRED)
  find_package(Sphinx REQUIRED)
  

• 更改FindSphinx.cmake模块中的sphinx-build查找逻辑,优先在当前使用的python3所在的bin目录路径下查找sohinx-build:

   # 先查找python可执行文件的bin目录
     execute_process(
         COMMAND python -c "import sys; print(sys.prefix)"
         OUTPUT_VARIABLE PYTHON_PREFIX
         OUTPUT_STRIP_TRAILING_WHITESPACE
     )
     set(PYTHON_BIN_DIR "${PYTHON_PREFIX}/bin")
     
     find_program(SPHINX_EXECUTABLE NAMES sphinx-build
       HINTS
       ${PYTHON_BIN_DIR}  # 优先在该路径下查找sphinx-build进行文档构建
       HINTS
       $ENV{SPHINX_DIR}
       HINTS ${SPHINX_ROOT}/bin
       PATH_SUFFIXES bin
       DOC "Sphinx documentation generator"
     )
        ```
  
  

---

总结

由于本机的python环境与数据示例代码中的运行环境不一致导致示例代码无法运行成功,可根据书中介绍的执行步骤检查本机环境配置情况进行分析解决;