Hello, Doxygen!

Generating Documentation From annotated 'C/C++'s Sources

@Gitter :gitter.im/cnruby
Code ID: basic_118
Code Name: Hello, Doxygen!

Youtube Video

TABLE of CONTENTS

• Requirements
  • Install Doxygen and Graphviz on MacOS
• Illustrate the Method of Generation 'Doxygen's API Documentation
  • Get The Code with Shell Commands
  • How to Suppress developer warnings
  • Illustrate Hiding developer warnings
  • What is The Command for Generating 'Doxygen's API Documentation
  • Illustrate Generating 'Doxygen's API Documentation
• The CMake File of The Project
  • The Listfile of Folder 'cmake'
  • Commands for Illustrating the Parameter "WORKING_DIRECTORY"
  • Illustrate the Parameter "WORKING_DIRECTORY"
• The Structures of Project
  • The Folder's Structure
  • The Command's Structure
  • The Process's Structure
• Final Summary
• References
• The Project's Commands
  • Formatting The Codes
  • Get The Code with Shell Commands
  • Build and Run The Project

Requirements

• VS Code 1.43.0+
• CMake 3.17.0+
• Tool Doxygen
• Tool Graphviz

Install Doxygen and Graphviz on MacOS

brew install doxygen
brew cask install graphviz

Illustrate the Method of Generation 'Doxygen's API Documentation

Get The Code with Shell Commands

git clone https://github.com/cnruby/w3h1_cmake.git basic_118
cd basic_118
git checkout basic_118
code .

How to Suppress developer warnings

# Create Build Folder
cmake -GNinja -Bbuild/
# show developer warnings: "This warning is for project developers."
cmake --build build/ --target rebuild_cache
# get help
cmake --help | grep dev
# change CMake cahce to hide developer warnings
ccmake -Wno-dev --build build/
# "c", "g", "q"
cmake --build build/ --target rebuild_cache
code ./build/CMakeCache.txt
# Goto 346

Illustrate Hiding developer warnings

What is The Command for Generating 'Doxygen's API Documentation

# Where do The Commands for generate docs come from
cmake --build build/ --target help
# Generate 'Doxygen's API Documentation
cmake --build build --target target_doxygen
# Open 'Doxygen's API Documentation
open build-docs/index.html

Illustrate Generating 'Doxygen's API Documentation

The CMake File of The Project

#<!-- markdown-exec(cmd:cat cmake/CMakeLists.txt) -->#
find_package(Doxygen REQUIRED dot)
if (DOXYGEN_FOUND)
  set(DOXYGEN_OUTPUT_DIRECTORY      ${PROJECT_SOURCE_DIR}/build-docs) 
  set(DOXYGEN_EXTRACT_ALL            YES)
  set(DOXYGEN_BUILTIN_STL_SUPPORT    YES)
  set(DOXYGEN_WARN_NO_PARAMDOC       YES)
  set(DOXYGEN_HTML_OUTPUT            .)
  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
  set(DOXYGEN_FILE_PATTERNS           *.c *.cc *.cxx *.cpp *.c++ *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.inc README.md)
  doxygen_add_docs(
    target_doxygen   # cmake --build build --target target_doxygen
    ${PROJECT_SOURCE_DIR}                 # Sources root directory
    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR} # change the directory used as the relative base poin
    COMMENT "Generate html pages"
  )
  #
  execute_process(
    COMMAND echo "cp docs"
    COMMAND mkdir -p ${PROJECT_SOURCE_DIR}/build-docs/docs/118/image
    COMMAND cp -rf ${PROJECT_SOURCE_DIR}/docs/118/image ${PROJECT_SOURCE_DIR}/build-docs/docs/118/
  )
else()
  message(STATUS "Doxygen not found, not building docs")
endif ()
message(STATUS "Doxygen Version: ${DOXYGEN_VERSION}")
#º<!-- /markdown-exec -->

The Listfile of Folder 'cmake'

Commands for Illustrating the Parameter "WORKING_DIRECTORY"

open build-docs/index.html
code cmake/CMakeLists.txt
# comment "WORKING_DIRECTORY"
cmake --build build/ --target rebuild_cache
cmake --build build --target target_doxygen
open build-docs/index.html

Illustrate the Parameter "WORKING_DIRECTORY"

The Structures of Project

#<!-- markdown-exec(cmd:cat docs/output/tree.txt) -->#
.                          >>>PROJECT_SOURCE_DIR
├── build-docs             >>>DOXYGEN_OUTPUT_DIRECTORY
├── CMakeLists.txt
├── cmake
│  └── CMakeLists.txt
├── README.md              >>>DOXYGEN_USE_MDFILE_AS_MAINPAGE
└── src
   ├── CMakeLists.txt
   └── main.cxx
#<!-- /markdown-exec -->

The Folder's Structure

The Command's Structure

The Process's Structure

Final Summary

感谢大家观看!

@Gitter: gitter.im/cnruby

@Github: github.com/cnruby

@Twitter: twitter.com/cnruby

@Blogspot: cnruby.blogspot.com

References

• https://cmake.org/cmake/help/latest/module/FindDoxygen.html
• https://gitlab.com/CLIUtils/modern-cmake/-/tree/master/examples/extended-project
• https://stackoverflow.com/questions/37315378/supressing-warning-in-building-opencv-with-cmake
• https://kubasejdak.com/19-reasons-why-cmake-is-actually-awesome#17-cmake-allows-generation-of-doxygen-docs-without-the-hardcoded-config
• http://macappstore.org/doxygen/
• http://www.doxygen.nl/
• http://macappstore.org/doxygen/
• http://macappstore.org/graphviz-2/
• http://graphviz.org/
• https://stackoverflow.com/questions/24488250/check-graphviz-installed-version-on-ubuntu

The Project's Commands

Formatting The Codes

ruby format-codes.rb

Get The Code with Shell Commands

git clone https://github.com/cnruby/w3h1_cmake.git basic_118
cd basic_118
git checkout basic_118
code .

Build and Run The Project

cmake -GNinja -Bbuild/
cmake --build build/ --clean-first -v
cmake --build build/ --target clean
cmake --build build/ --clean-first -v &> v11.txt
# generate the configure file
rm -rf config
cmake --build build/ --clean-first
cmake -Bbuild/
cmake --build build/ --target rebuild_cache
cmake --build build/ --clean-first
./bin/main_118
#  update the configure file
cmake --build build/ --clean-first
# others
code build/build.ninja
cmake --check-system-vars --build build/
cmake --help-command find_package | less


# show this dev Info "This warning is for project developers."
cmake -GNinja -Bbuild/
cmake -Bbuild/
cmake --help | grep dev
ccmake -Wno-dev --build build/
cmake -Bbuild/
open ./build/CMakeCache.txt
# Goto 346
# show no dev info
cmake -Bbuild/


# Where do The Commands for generate docs come from
cmake --build build/ --target help
cmake --build build/ --target rebuild_cache


# generate docs
cmake --build build/ --target help
cmake --build build --target target_doxygen
open build-docs/index.html


markdown-exec README.md
ruby format-codes.rb
git branch -vv
git checkout -b basic_118
exa -T > docs/output/tree.txt
dot -V
doxygen --version