{"id":24393,"date":"2019-06-03T14:44:03","date_gmt":"2019-06-03T14:44:03","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=24393"},"modified":"2019-06-03T14:44:03","modified_gmt":"2019-06-03T14:44:03","slug":"clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake\/","title":{"rendered":"Clear, Functional C++ Documentation with Sphinx + Breathe + Doxygen + CMake"},"content":{"rendered":"

Writing good documentation is hard. Tools can\u2019t solve this problem in themselves, but they can ease the pain. This post will show you how to use Sphinx<\/a> to generate attractive, functional documentation for C++ libraries, supplied with information from Doxygen<\/a>. We\u2019ll also integrate this process into a CMake<\/a> build system so that we have a unified workflow.<\/p>\n

For an example of a real-world project whose documentation is built like this, see fmtlib<\/a>.<\/p>\n

Why Sphinx?<\/h2>\n

Doxygen has been around for a couple of decades and is a stable, feature-rich tool for generating documentation. However, it is not without its issues. Docs generated with Doxygen tend to be visually noisy, have a style out of the early nineties, and struggle to clearly represent complex template-based APIs. There are also limitations to its markup. Although they added Markdown support in 2012, Markdown is simply not the best tool for writing technical documentation since it sacrifices extensibility, featureset size, and semantic markup for simplicity.<\/p>\n

Sphinx instead uses reStructuredText<\/a>, which has those important concepts which are missing from Markdown as core ideals. One can add their own \u201croles\u201d and \u201cdirectives\u201d to the markup to make domain-specific customizations. There are some great comparisons of reStructuredText and Markdown by <\/a>Victor <\/a>Zverovich<\/a> and Eli Bendersky<\/a> if you\u2019d like some more information.<\/p>\n

The docs generated by Sphinx also look a lot more modern and minimal when compared to Doxygen and it\u2019s much easier to swap in a different theme, customize the amount of information which is displayed, and modify the layout of the pages.<\/p>\n

\n
\n

\"Doxygen's
Doxygen output<\/figcaption><\/figure><\/p>\n<\/div>\n
\n

\"Output
Sphinx output<\/figcaption><\/figure><\/p>\n<\/div>\n<\/div>\n

 <\/p>\n

On a more fundamental level, Doxygen\u2019s style of documentation is listing out all the API entities along with their associated comments in a more digestible, searchable manner. It\u2019s essentially paraphrasing the header files, to take a phrase from Robert Ramey<\/a>[1]<\/a><\/sup>; embedding things like rationale, examples, notes, or swapping out auto-generated output for hand-written is not very well supported. In Sphinx however, the finer-grained control gives you the ability to write documentation which is truly geared towards getting people to learn and understand your library.<\/p>\n

If you\u2019re convinced that this is a good avenue to explore, then we can begin by installing dependencies.<\/p>\n

Install Dependencies<\/h2>\n

Doxygen<\/h2>\n

Sphinx doesn\u2019t have the ability to extract API documentation from C++ headers; this needs to be supplied either by hand or from some external tool. We can use Doxygen to do this job for us. Grab it from the official download page<\/a> and install it. There are binaries for Windows, Linux (compiled on Ubuntu 16.04), and MacOS, alongside source which you can build yourself.<\/p>\n

Sphinx<\/h2>\n

Pick your preferred way of installing Sphinx from the official instructions<\/a>. It may be available through your system package manager, or you can get it through pip<\/a>.<\/p>\n

Read the Docs Sphinx Theme<\/h2>\n

I prefer this theme to the built-in ones, so we can install it through pip:<\/p>\n

> pip install sphinx_rtd_theme<\/pre>\n
Breathe<\/h2>\n
Breathe is the bridge between Doxygen and Sphinx; taking the output from the former and making it available through some special directives in the latter. You can install it with pip:<\/p>\n
> pip install breathe<\/pre>\n
CMake<\/h2>\n
Install the latest release of CMake<\/a>. If you are using Visual Studio 2017 and up, you will already have a version installed and ready to use. See CMake projects in Visual Studio<\/a> for more details.<\/p>\n
Create a CMake Project<\/h2>\n
All of the code for this post is available on Github<\/a>, so if you get stuck, have a look there.<\/p>\n
If you are using Visual Studio 2017 and up, go to File > New > Project and create a CMake project.<\/p>\n
\"Create<\/p>\n
 <\/p>\n
Regardless of which IDE\/editor you are using, get your project folder to look something like this:<\/p>\n
CatCutifier\/CMakeLists.txt<\/h4>\n
cmake_minimum_required (VERSION 3.8)\r\n\r\nproject (\"CatCutifier\")\r\n\r\nadd_subdirectory (\"CatCutifier\")<\/pre>\n
CatCutifier\/CatCutifier\/CatCutifier.cpp<\/h4>\n
#include \"CatCutifier.h\"\r\n\r\nvoid cat::make_cute() {\r\n  \/\/ Magic happens\r\n}<\/pre>\n
CatCutifier\/CatCutifier\/CatCutifier.h<\/h4>\n
#pragma once\r\n\r\n\/**\r\n  A fluffy feline\r\n*\/\r\nstruct cat {\r\n  \/**\r\n    Make this cat look super cute\r\n  *\/\r\n  void make_cute();\r\n};<\/pre>\n
CatCutifier\/CatCutifier\/CMakeLists.txt<\/h4>\n
add_library (CatCutifier \"CatCutifier.cpp\" \"CatCutifier.h\")\r\n\r\ntarget_include_directories(CatCutifier PUBLIC .)<\/pre>\n
If you now build your project, you should get a CatCutifier library which someone could link against and use.<\/p>\n
Now that we have our library, we can set up document generation.<\/p>\n
Set up Doxygen<\/h2>\n
If you don\u2019t already have Doxygen set up for your project, you\u2019ll need to generate a configuration file so that it knows how to generate docs for your interfaces. Make sure the Doxygen executable is on your path and run:<\/p>\n
> mkdir docs\r\n> cd docs\r\n> doxygen.exe -g<\/pre>\n
You should get a message like:<\/p>\n
Configuration file `Doxyfile' created.\r\nNow edit the configuration file and enter\r\n  doxygen Doxyfile\r\nto generate the documentation for your project<\/pre>\n
We can get something generated quickly by finding the INPUT variable in the generated Doxyfile and pointing it at our code:<\/p>\n
INPUT = ..\/CatCutifier<\/pre>\n
Now if you run:<\/p>\n
> doxygen.exe<\/pre>\n
You should get an html folder generated which you can point your browser at and see some documentation like this:<\/p>\n
\"Doxygen's<\/p>\n
We\u2019ve successfully generated some simple documentation for our class by hand. But we don\u2019t want to manually run this command every time we want to rebuild the docs; this should be handled by CMake.<\/p>\n
Doxygen in CMake<\/h2>\n
To use Doxygen from CMake, we need to find the executable. Fortunately CMake provides a find module<\/a> for Doxygen, so we can use find_package(Doxygen REQUIRED) to locate the binary and report an error if it doesn\u2019t exist. This will store the executable location in the DOXYGEN_EXECUTABLE variable, so we can add_custom_command<\/a> to run it and track dependencies properly:<\/p>\n
CatCutifier\/CMakeLists.txt<\/h4>\n
cmake_minimum_required (VERSION 3.8)\r\nproject (\"CatCutifier\")\r\nadd_subdirectory (\"CatCutifier\")\r\nadd_subdirectory (\"docs\")<\/pre>\n
CatCutifier\/docs\/CMakeLists.txt<\/h4>\n
find_package(Doxygen REQUIRED)\r\n\r\n# Find all the public headers\r\nget_target_property(CAT_CUTIFIER_PUBLIC_HEADER_DIR CatCutifier INTERFACE_INCLUDE_DIRECTORIES)\r\nfile(GLOB_RECURSE CAT_CUTIFIER_PUBLIC_HEADERS ${CAT_CUTIFIER_PUBLIC_HEADER_DIR}\/*.h)\r\n\r\n#This will be the main output of our command\r\nset(DOXYGEN_INDEX_FILE ${CMAKE_CURRENT_SOURCE_DIR}\/html\/index.html)\r\n\r\nadd_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}\r\n                   DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}\r\n                   COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile\r\n                   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}\r\n                   MAIN_DEPENDENCY Doxyfile\r\n                   COMMENT \"Generating docs\")\r\n\r\nadd_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})<\/pre>\n
The final custom target makes sure that we have a target name to give to make and that dependencies will be checked for a rebuild whenever we Build All or do a bare make.<\/p>\n
We also want to be able to control the input and output directories from CMake so that we\u2019re not flooding our source directory with output files. We can do this by adding some placeholders to our Doxyfile (we\u2019ll rename it Doxyfile.in to follow convention) and having CMake fill them in with configure_file<\/a>:<\/p>\n
CatCutifier\/docs\/Doxyfile.in<\/h4>\n
#...\r\nINPUT = \"@DOXYGEN_INPUT_DIR@\"\r\n#...\r\nOUTPUT_DIRECTORY = \"@DOXYGEN_OUTPUT_DIR@\"\r\n#...<\/pre>\n
CatCutifier\/docs\/CMakeLists.txt<\/h4>\n
find_package(Doxygen REQUIRED)\r\n\r\n# Find all the public headers\r\nget_target_property(CAT_CUTIFIER_PUBLIC_HEADER_DIR CatCutifier INTERFACE_INCLUDE_DIRECTORIES)\r\nfile(GLOB_RECURSE CAT_CUTIFIER_PUBLIC_HEADERS ${CAT_CUTIFIER_PUBLIC_HEADER_DIR}\/*.h)\r\n\r\nset(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}\/CatCutifier)\r\nset(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}\/docs\/doxygen)\r\nset(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}\/html\/index.html)\r\nset(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}\/Doxyfile.in)\r\nset(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}\/Doxyfile)\r\n\r\n#Replace variables inside @@ with the current values\r\nconfigure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)\r\n\r\nfile(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) #Doxygen won't create this for us\r\nadd_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}\r\n                   DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}\r\n                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}\r\n                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}\r\n                   COMMENT \"Generating docs\")\r\n\r\nadd_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})<\/pre>\n
Now we can generate our documentation as part of our build system and it\u2019ll only be generated when it needs to be. If you\u2019re happy with Doxygen\u2019s output, you could just stop here, but if you want the additional features and attractive output which reStructuredText and Sphinx give you, then read on.<\/p>\n
Setting up Sphinx<\/h2>\n
Sphinx provides a nice startup script to get us going fast. Go ahead and run this:<\/p>\n
> cd docs\r\n> sphinx-quickstart.exe<\/pre>\n
Keep the defaults and put in your name and the name of your project. Now if you run make html you should get a _build\/html folder you can point your browser at to see a welcome screen.<\/p>\n
\"Front<\/p>\n
I\u2019m a fan of the Read the Docs theme we installed at the start, so we can use that instead by changing html_theme in conf.py to be \u2018sphinx_rtd_theme\u2019. That gives us this look:<\/p>\n
\"The<\/p>\n
Before we link in the Doxygen output to give us the documentation we desire, lets automate the Sphinx build with CMake<\/p>\n
Sphinx in CMake<\/h2>\n
Ideally we want to be able to write find_package(Sphinx REQUIRED) and have everything work. Unfortunately, unlike Doxygen, Sphinx doesn\u2019t have a find module provided by default, so we\u2019ll need to write one. Fortunately, we can get away with doing very little work:<\/p>\n
CatCutifier\/cmake\/FindSphinx.cmake<\/h4>\n
#Look for an executable called sphinx-build\r\nfind_program(SPHINX_EXECUTABLE\r\n             NAMES sphinx-build\r\n             DOC \"Path to sphinx-build executable\")\r\n\r\ninclude(FindPackageHandleStandardArgs)\r\n\r\n#Handle standard arguments to find_package like REQUIRED and QUIET\r\nfind_package_handle_standard_args(Sphinx\r\n                                  \"Failed to find sphinx-build executable\"\r\n                                  SPHINX_EXECUTABLE)<\/pre>\n
With this file in place, find_package will work so long as we tell CMake to look for find modules in that directory:<\/p>\n
CatCutifier\/CMakeLists.txt<\/h4>\n
cmake_minimum_required (VERSION 3.8)\r\n\r\nproject (\"CatCutifier\")\r\n\r\n# Add the cmake folder so the FindSphinx module is found\r\nset(CMAKE_MODULE_PATH \"${PROJECT_SOURCE_DIR}\/cmake\" ${CMAKE_MODULE_PATH})\r\n\r\nadd_subdirectory (\"CatCutifier\")\r\nadd_subdirectory (\"docs\")<\/pre>\n
Now we can find this executable and call it:<\/p>\n
CatCutifier\/docs\/CMakeLists.txt<\/h4>\n
find_package(Sphinx REQUIRED)\r\n\r\nset(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})\r\nset(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}\/docs\/sphinx)\r\n\r\nadd_custom_target(Sphinx ALL\r\n                  COMMAND\r\n                  ${SPHINX_EXECUTABLE} -b html\r\n                  ${SPHINX_SOURCE} ${SPHINX_BUILD}\r\n                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\r\n                  COMMENT \"Generating documentation with Sphinx\")<\/pre>\n
If you run a build you should now see Sphinx running and generating the same blank docs we saw earlier.<\/p>\n
Now we have the basics set up, we need to hook Sphinx up with the information generated by Doxygen. We do that using Breathe.<\/p>\n
Setting up Breathe<\/h2>\n
Breathe is an extension to Sphinx, so we set it up using the conf.py which was generated for us in the last step:<\/p>\n
CatCutifier\/docs\/conf.py<\/h4>\n
#...\r\nextensions = [ \"breathe\" ]\r\n#...\r\n\r\n# Breathe Configuration\r\nbreathe_default_project = \"CatCutifier\"<\/pre>\n
Breathe uses Doxygen\u2019s XML output, which is disabled by default, so we need to turn it on:<\/p>\n
CatCutifier\/docs\/Doxyfile.in<\/h4>\n
#...\r\nGENERATE_XML = YES\r\n#...<\/pre>\n
We\u2019ll need to put placeholders in our docs to tell Sphinx where to put our API information. We achieve this with directives supplied by Breathe<\/a>, such as doxygenstruct<\/a>:<\/p>\n
CatCutifier\/docs\/index.rst<\/h4>\n
\u2026\r\n\r\nDocs\r\n====\r\n\r\n.. doxygenstruct:: cat\r\n   :members:<\/pre>\n
You might wonder why it\u2019s necessary to explicitly state what entities we wish to document and where, but this is one of the key benefits of Sphinx. This allows us to add as much additional information (examples, rationale, notes, etc.) as we want to the documentation without having to shoehorn it into the source code, plus we can make sure it\u2019s displayed in the most accessible, understandable manner we can. Have a look through Breathe\u2019s directives<\/a> and Sphinx\u2019s built-in directives<\/a>, and Sphinx\u2019s C++-specific directives<\/a> to get a feel for what\u2019s available.<\/p>\n
Now we update our Sphinx target to hook it all together by telling Breathe where to find the Doxygen output:<\/p>\n
CatCutifier\/docs\/CMakeLists.txt<\/h4>\n
#...\r\n\r\nfind_package(Sphinx REQUIRED)\r\n\r\nset(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})\r\nset(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}\/docs\/sphinx)\r\n\r\nadd_custom_target(Sphinx ALL\r\n                  COMMAND ${SPHINX_EXECUTABLE} -b html\r\n                  # Tell Breathe where to find the Doxygen output\r\n                  -Dbreathe_projects.CatCutifier=${DOXYGEN_OUTPUT_DIR}\r\n                  ${SPHINX_SOURCE} ${SPHINX_BUILD}\r\n                  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\r\n                  COMMENT \"Generating documentation with Sphinx\")<\/pre>\n
Hooray! You should now have some nice Sphinx documentation generated for you:<\/p>\n
\"Output<\/p>\n
Finally, we can make sure all of our dependencies are right so that we never rebuild the Doxygen files or the Sphinx docs when we don\u2019t need to:<\/p>\n
CatCutifier\/docs\/CMakeLists.txt<\/h4>\n
find_package(Doxygen REQUIRED)\r\nfind_package(Sphinx REQUIRED)\r\n\r\n# Find all the public headers\r\nget_target_property(CAT_CUTIFIER_PUBLIC_HEADER_DIR CatCutifier INTERFACE_INCLUDE_DIRECTORIES)\r\nfile(GLOB_RECURSE CAT_CUTIFIER_PUBLIC_HEADERS ${CAT_CUTIFIER_PUBLIC_HEADER_DIR}\/*.h)\r\n\r\nset(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}\/CatCutifier)\r\nset(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}\/doxygen)\r\nset(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}\/xml\/index.xml)\r\nset(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}\/Doxyfile.in)\r\nset(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}\/Doxyfile)\r\n\r\n# Replace variables inside @@ with the current values\r\nconfigure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)\r\n\r\n# Doxygen won't create this for us\r\nfile(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})\r\n\r\n# Only regenerate Doxygen when the Doxyfile or public headers change\r\nadd_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}\r\n                   DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}\r\n                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}\r\n                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}\r\n                   COMMENT \"Generating docs\"\r\n                   VERBATIM)\r\n\r\n# Nice named target so we can run the job easily\r\nadd_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})\r\n\r\nset(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})\r\nset(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}\/sphinx)\r\nset(SPHINX_INDEX_FILE ${SPHINX_BUILD}\/index.html)\r\n\r\n# Only regenerate Sphinx when:\r\n# - Doxygen has rerun\r\n# - Our doc files have been updated\r\n# - The Sphinx config has been updated\r\nadd_custom_command(OUTPUT ${SPHINX_INDEX_FILE}\r\n                   COMMAND \r\n                     ${SPHINX_EXECUTABLE} -b html\r\n                     # Tell Breathe where to find the Doxygen output\r\n                     -Dbreathe_projects.CatCutifier=${DOXYGEN_OUTPUT_DIR}\/xml\r\n                   ${SPHINX_SOURCE} ${SPHINX_BUILD}\r\n                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}\r\n                   DEPENDS\r\n                   # Other docs files you want to track should go here (or in some variable)\r\n                   ${CMAKE_CURRENT_SOURCE_DIR}\/index.rst\r\n                   ${DOXYGEN_INDEX_FILE}\r\n                   MAIN_DEPENDENCY ${SPHINX_SOURCE}\/conf.py\r\n                   COMMENT \"Generating documentation with Sphinx\")\r\n\r\n# Nice named target so we can run the job easily\r\nadd_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})\r\n\r\n# Add an install target to install the docs\r\ninclude(GNUInstallDirs)\r\ninstall(DIRECTORY ${SPHINX_BUILD}\r\nDESTINATION ${CMAKE_INSTALL_DOCDIR})<\/pre>\n
Try it out and see what gets rebuilt when you change a file. If you change Doxyfile.in or a header file, all the docs should get rebuilt, but if you only change the Sphinx config or reStructuredText files then the Doxygen build should get skipped.<\/p>\n
This leaves us with an efficient, automated, powerful documentation system.<\/p>\n
If you already have somewhere to host the docs or want developers to build the docs themselves then we\u2019re finished. If not, you can host them on Read the Docs<\/a>, which provides free hosting for open source projects.<\/p>\n
Setting up Read the Docs<\/em><\/h2>\n
To use Read the Docs (RtD) you need to sign up<\/a> (you can use GitHub, GitLab or Bitbucket to make integration easy). Log in, import your repository, and your docs will begin to build!<\/p>\n
Unfortunately, it will also fail:<\/p>\n
Traceback (most recent call last): File \"\/home\/docs\/checkouts\/readthedocs.org\/user_builds\/cpp-documentation-example\/envs\/latest\/lib\/python3.7\/site-packages\/sphinx\/registry.py\", line 472, in load_extension mod = __import__(extname, None, None, ['setup']) ModuleNotFoundError: No module named 'breathe'<\/pre>\n
To tell RtD to install Breathe before building, we can add a requirements file:<\/p>\n
CatCutifier\/docs\/requirements.txt<\/h4>\n
breathe<\/pre>\n
Another issue is that RtD doesn\u2019t understand CMake: it\u2019s finding the Sphinx config file and running that, so it won\u2019t generate the Doxygen information. To generate this, we can add some lines to our conf.py script to check if we\u2019re running in on the RtD servers and, if so, hardcode some paths and run Doxygen:<\/p>\n
CatCutifier\/docs\/conf.py<\/h4>\n
import subprocess, os\r\n\r\ndef configureDoxyfile(input_dir, output_dir):\r\n    with open('Doxyfile.in', 'r') as file :\r\n        filedata = file.read()\r\n\r\n    filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir)\r\n    filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', output_dir)\r\n\r\n    with open('Doxyfile', 'w') as file:\r\n        file.write(filedata)\r\n\r\n# Check if we're running on Read the Docs' servers\r\nread_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'\r\n\r\nbreathe_projects = {}\r\n\r\nif read_the_docs_build:\r\n    input_dir = '..\/CatCutifier'\r\n    output_dir = 'build'\r\n    configureDoxyfile(input_dir, output_dir)\r\n    subprocess.call('doxygen', shell=True)\r\n    breathe_projects['CatCutifier'] = output_dir + '\/xml'\r\n\r\n# ...<\/pre>\n
Push this change and\u2026<\/p>\n
\"Full<\/p>\n
Lovely documentation built automatically on every commit.<\/p>\n
Conclusion<\/h2>\n
All this tooling takes a fair amount of effort to set up, but the result is powerful, expressive, and accessible. None of this is a substitute for clear writing and a strong grasp of what information a user of a library needs to use it effectively, but our new system can provide support to make this easier for developers.<\/p>\n
Resources<\/h2>\n
Thank you to the authors and presenters of these resources, which were very helpful in putting together this post and process:<\/p>\n
https:\/\/vicrucann.github.io\/tutorials\/quick-cmake-doxygen\/<\/a><\/p>\n
https:\/\/eb2.co\/blog\/2012\/03\/sphinx-and-cmake-beautiful-documentation-for-c—projects\/<\/a><\/p>\n
https:\/\/nazavode.github.io\/blog\/cmake-doxygen-improved\/<\/a><\/p>\n
http:\/\/www.zverovich.net\/2016\/06\/16\/rst-vs-markdown.html<\/a><\/p>\n
https:\/\/eli.thegreenplace.net\/2017\/restructuredtext-vs-markdown-for-technical-documentation\/<\/a><\/p>\n
https:\/\/www.youtube.com\/watch?v=YxmdCxX9dMk<\/a><\/p>\n
    \n
  1. I would highly recommend watching this talk to help you think about what you put in your documentation. \u2191<\/a><\/li>\n<\/ol>\n
     <\/p>\n","protected":false},"excerpt":{"rendered":"
    Writing good documentation is hard. Tools can\u2019t solve this problem in themselves, but they can ease the pain. This post will show you how to use Sphinx to generate attractive, functional documentation for C++ libraries, supplied with information from Doxygen. We\u2019ll also integrate this process into a CMake build system so that we have a […]<\/p>\n","protected":false},"author":706,"featured_media":24411,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[512],"tags":[],"class_list":["post-24393","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-general-cpp-series"],"acf":[],"blog_post_summary":"
    Writing good documentation is hard. Tools can\u2019t solve this problem in themselves, but they can ease the pain. This post will show you how to use Sphinx to generate attractive, functional documentation for C++ libraries, supplied with information from Doxygen. We\u2019ll also integrate this process into a CMake build system so that we have a […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/24393","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/706"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=24393"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/24393\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/24411"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=24393"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=24393"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=24393"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}