Generate c++ documentation using sphinx through Eigen
-
System environment: win10+CMake+Doxygen+Sphinx+Breathe+Eigen+python
-
The C++ standard documentation system is Doxygen, and Sphinx is mainly used to generate python documentation. If you want to use Sphinx to generate c++ standard documents, you need to convert Breathe and Eigen.
The figure above shows the version conflict of Eigen. The relevant documents are given below, and those who are interested can refer to them.
Doxygen Official Documentation
Sphinx Official Documentation
Breathe Official Documentation
Eigen Official Documentation -
Doxygen installation and simple use, please refer to the link for details: https://www.cnblogs.com/gentletk/p/16536564.html, double-click doxygen.exe to install, and the installation is complete.
-
Install Sphinx+Breathe+Eigen.
All three can be installed with pip, provided that python and pip are installed.
pip install exhale
pip install sphinx
pip install breathe -
After installing Ancheng, use the sphinx-quickstart command to quickly generate conf.py and index.rst file templates. This command is recommended to be run on the docs file, and some information needs to be filled in during the generation process. The final generated files include the source subfolder under docs, make.bat, Makefile, and the most important conf.py file and index.rst file under the source folder. conf.py is the Sphinx configuration file, which needs to include plug-in configuration and other parameter settings. Because Exhale is needed to help convert sphinx, Exhale needs to be injected into conf.py. The configuration method is shown in the figure below, please refer to the document for details. In the configuration file, the most important parameter is the INPUT parameter in "exhaleDoxygenStdin". Simply put, if you want to generate the documentation of that module, you need to fill in the relative path of this module here.
After this operation, doxygen can be called to generate documents, but it still needs to be displayed on the page. This requires adding the rootFile defined in the exhale_args object to index.rst. api/library_root in the figure below. Note that these files must be placed under the toctree command, and cannot be connected with the options indicated by the colon above, and a blank line is required.
Finally, run make html in the docs directory to generate html documents, which is the document directory after running.
Finally, open the index.html pointed by the red arrow with a browser.
This article only shows some of the most basic operations, and the specific functions need to be further developed.
Remarks: If you only want to use doxygen to generate c++ documents, you need to configure it after doxygen is installed. There are two configuration methods. The first is to open Start-"All Programs-"Doxygen-"doxywizard to configure using the ui interface; the second is to use the file method to configure, and the final purpose is to generate Doxyfile. This article takes the second method as an example.
The project directory structure used in this article is shown in the figure below:
For a new project, a doxyfile template is generated through doxygen -g. This template is very long and needs to be configured by yourself.
Finally run doxygen Doxyfile.