网站服务器升级需要多久,2345浏览器网页,如何做 网站映射,饰品设计制作培训Sphinx Breathe Doxygen CMake 的教程看这个就够了
https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
但是他还是少写了一些东西#xff0c;所以还是有一些小坑的
这些坑会导致 Sphinx 找不到 Doxygen 导出…Sphinx Breathe Doxygen CMake 的教程看这个就够了
https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
但是他还是少写了一些东西所以还是有一些小坑的
这些坑会导致 Sphinx 找不到 Doxygen 导出的 xml 中的内容或者是报错
第一个是 conf.py 可能一直找不到 sphinx_rtd_theme 这个 module即使你更新了 pip重新下载了 sphinx_rtd_theme 好多遍也没有办法
这个原因很简单就是因为他没有找到你的 python 下载包的路径
我的 cmake 配置如下主要是设置了一个虚拟环境放在输出目录中这样我们就可以不污染主机的 python 环境也可以清楚地知道自己的包下载到哪里了
projectRoot/CMakeLists.txt
...# Docs only available if this is the main app
find_package(Doxygen)
if(Doxygen_FOUND)message(STATUS Found Doxygen, building docs)add_subdirectory(docs)
else()message(STATUS Doxygen not found, not building docs)
endif()projectRoot/docs/CMakeLists.txt
option(BUILD_DOCS_USE_VENV Generate Python virtual environment ON)find_package(Python COMPONENTS Interpreter REQUIRED)
if (BUILD_DOCS_USE_VENV)set(DOCS_VENV ${CMAKE_CURRENT_BINARY_DIR}/venv)message(STATUS Creating Python venv at ${DOCS_VENV})execute_process(COMMAND ${Python_EXECUTABLE} -m venv ${DOCS_VENV})set(ENV{VIRTUAL_ENV} ${DOCS_VENV})set(Python_FIND_VIRTUALENV FIRST)unset(Python_EXECUTABLE)find_package(Python COMPONENTS Interpreter REQUIRED)execute_process(COMMAND ${Python_EXECUTABLE} -m pip install --no-cache wheelWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY)execute_process(COMMAND ${Python_EXECUTABLE} -m pip install --no-cache -r requirements.txtWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY)
endif()execute_process(COMMAND ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../helper/req_check.py requirements.txtWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY
)find_program(SPHINX_EXECUTABLE sphinx-build HINTS ${DOCS_VENV}/Scripts ${DOCS_VENV}/bin REQUIRED)
message(STATUS Found Sphinx: ${SPHINX_EXECUTABLE})# Find all the public headers from runtime
get_target_property(RUNTIME_PUBLIC_HEADER_DIR ${RUNTIME_NAME} INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE RUNTIME_PUBLIC_HEADERS CONFIGURE_DEPENDS ${RUNTIME_PUBLIC_HEADER_DIR}/*.h)# Find all the public headers from editor
get_target_property(EDITOR_PUBLIC_HEADER_DIR ${EDITOR_NAME} INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE EDITOR_PUBLIC_HEADERS CONFIGURE_DEPENDS ${EDITOR_PUBLIC_HEADER_DIR}/*.h)message(--------------)
message(STATUS ${RUNTIME_PUBLIC_HEADERS})
message(STATUS ${EDITOR_PUBLIC_HEADERS})
message(--------------)set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)# Replace variables inside with the current values
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} ONLY)# Doxygen wont create this for us
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})# Only regenerate Doxygen when the Doxyfile or public headers change
add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}DEPENDS ${RUNTIME_PUBLIC_HEADERS} ${EDITOR_PUBLIC_HEADERS}COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}COMMENT Generating docsVERBATIM)# Nice named target so we can run the job easily
add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)# Only regenerate Sphinx when:
# - Doxygen has rerun
# - Our doc files have been updated
# - The Sphinx config has been updated
add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}COMMAND ${SPHINX_EXECUTABLE} -b html# Tell Breathe where to find the Doxygen output-Dbreathe_projects.MeowEngine${DOXYGEN_OUTPUT_DIR}/xml${SPHINX_SOURCE} ${SPHINX_BUILD}WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}DEPENDS# Other docs files you want to track should go here (or in some variable)${CMAKE_CURRENT_SOURCE_DIR}/index.rst${DOXYGEN_INDEX_FILE}MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.pyCOMMENT Generating documentation with Sphinx)# Nice named target so we can run the job easily
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})# Add an install target to install the docs
include(GNUInstallDirs)
install(DIRECTORY ${SPHINX_BUILD}
DESTINATION ${CMAKE_INSTALL_DOCDIR})其中获取 Doxygen 所需要的头文件那里那里是我自己的项目的情况一个 runtime 一个 engine这个具体实现因项目而异
然后我们现在已经知道自己下载的包在哪里了我们就在 conf.py 中直接把这个路径写进去
projectRoot/docs/conf.py
import sys
from pathlib import Pathsys.path.insert(0, str(Path(../build/docs/venv/Lib/site-packages/).resolve()))然后还有一点坑的就是在 conf.py 中我们要写明 breathe 的项目的名称和对应的 doxygen 输出的 xml 的位置
projectRoot/docs/conf.py
breathe_projects {MeowEngine: ../build/docs/doxygen/xml
}完整的 conf.py
projectRoot/docs/conf.py
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-informationimport sys
from pathlib import Pathsys.path.insert(0, str(Path(../build/docs/venv/Lib/site-packages/).resolve()))import sphinx_rtd_themeproject MeowEngine
copyright 2023, CheapMeow
author CheapMeow# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configurationextensions [sphinx_rtd_theme, breathe]breathe_projects {MeowEngine: ../build/docs/doxygen/xml
}templates_path [_templates]
exclude_patterns [_build, Thumbs.db, .DS_Store]# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-outputhtml_theme sphinx_rtd_theme
html_theme_path [sphinx_rtd_theme.get_html_theme_path()]
html_static_path [_static]如果现在 sphinx 还是没有办法找到你的类的话可能是你没有写明命名空间
projectRoot/docs/index.rst
.. doxygenclass:: Meow::MeowEngine:project: MeowEngine:members:因为你可以看到 xml 里面的输出是带着命名空间的
projectRoot/build/docs/doxygen/xml/class_meow_1_1_meow_engine.xml compounddef idclass_meow_1_1_meow_engine kindclass languageC protpubliccompoundnameMeow::MeowEngine/compoundname
