From 0f7ae8a3b79e6920786ba3f053e62a68d934b1f8 Mon Sep 17 00:00:00 2001 From: Krishna Chaitanya Date: Wed, 29 Jul 2020 16:16:13 +0530 Subject: [PATCH] Use m.css for generating doxygen docs (#49) * Use m.css for generating doxygen docs * pass CMake variables to Doxygen * Setup config for Pages section * show not explicitly documented objects * update patch comment * update comment on M_SHOW_UNDOCUMENTED Co-authored-by: Lars Melchior --- documentation/CMakeLists.txt | 36 ++++++++++++++++++++++------------- documentation/Doxyfile | 22 +++++++++++++-------- documentation/conf.py | 19 ++++++++++++++++++ documentation/pages/about.dox | 5 +++++ include/greeter/greeter.h | 6 +++--- 5 files changed, 64 insertions(+), 24 deletions(-) create mode 100644 documentation/conf.py create mode 100644 documentation/pages/about.dox diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 0a16fb9..3947179 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -12,25 +12,35 @@ CPMAddPackage( ) CPMAddPackage( - NAME StableCoder-cmake-scripts - GITHUB_REPOSITORY StableCoder/cmake-scripts - GIT_TAG 3d2d5a9fb26f0ce24e3e4eaeeff686ec2ecfb3fb + NAME MCSS + DOWNLOAD_ONLY YES + # patched version until https://github.com/mosra/m.css/pull/171 is resolved + GITHUB_REPOSITORY TheLartians/m.css + GIT_TAG 1bf162b96d5bfefc9967a80cef138f1270ffa415 ) -# ---- Doxygen ---- - -set(BUILD_DOCUMENTATION ON CACHE INTERNAL "") -include(${StableCoder-cmake-scripts_SOURCE_DIR}/doxygen.cmake) +# ---- Doxygen variables ---- # set Doxyfile variables set(DOXYGEN_PROJECT_NAME Greeter) set(DOXYGEN_PROJECT_VERSION ${Greeter_VERSION}) set(DOXYGEN_PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/..") +set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/doxygen") -# see https://github.com/StableCoder/cmake-scripts#doxygen-doxygencmake for additional options -build_docs( - TARGET_NAME GenerateDocs - DOXYFILE_PATH ${CMAKE_CURRENT_LIST_DIR}/Doxyfile - OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen - PROCESS_DOXYFILE ON +configure_file( + ${CMAKE_CURRENT_LIST_DIR}/Doxyfile + ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile +) + +configure_file( + ${CMAKE_CURRENT_LIST_DIR}/conf.py + ${CMAKE_CURRENT_BINARY_DIR}/conf.py +) + +add_custom_target( + GenerateDocs + ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIRECTORY}" + COMMAND "${MCSS_SOURCE_DIR}/documentation/doxygen.py" "${CMAKE_CURRENT_BINARY_DIR}/conf.py" + COMMAND echo "Docs written to: ${DOXYGEN_OUTPUT_DIRECTORY}" + WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" ) diff --git a/documentation/Doxyfile b/documentation/Doxyfile index c771bf3..2c33e00 100644 --- a/documentation/Doxyfile +++ b/documentation/Doxyfile @@ -7,19 +7,25 @@ PROJECT_NAME = @DOXYGEN_PROJECT_NAME@ PROJECT_NUMBER = @DOXYGEN_PROJECT_VERSION@ # Add sources -INPUT = @DOXYGEN_PROJECT_ROOT@/README.md @DOXYGEN_PROJECT_ROOT@/include @DOXYGEN_PROJECT_ROOT@/source +INPUT = @DOXYGEN_PROJECT_ROOT@/README.md @DOXYGEN_PROJECT_ROOT@/include @DOXYGEN_PROJECT_ROOT@/documentation/pages EXTRACT_ALL = YES RECURSIVE = YES - -# We don't want local paths in the documentation -FULL_PATH_NAMES = NO +OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@ # Use the README as a main page USE_MDFILE_AS_MAINPAGE = @DOXYGEN_PROJECT_ROOT@/README.md -# Create nicer looking HTML -HTML_DYNAMIC_SECTIONS = YES -GENERATE_TREEVIEW = YES +# set relative include paths +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = @DOXYGEN_PROJECT_ROOT@/include @DOXYGEN_PROJECT_ROOT@ -# We don't need LaTeX generation +# We use m.css to generate the html documentation, so we only need XML output +GENERATE_XML = YES +GENERATE_HTML = NO GENERATE_LATEX = NO +XML_PROGRAMLISTING = NO +CREATE_SUBDIRS = NO + +# Include all directories, files and namespaces in the documentation +# Disable to include only explicitly documented objects +M_SHOW_UNDOCUMENTED = YES diff --git a/documentation/conf.py b/documentation/conf.py new file mode 100644 index 0000000..6cc1a04 --- /dev/null +++ b/documentation/conf.py @@ -0,0 +1,19 @@ +DOXYFILE = 'Doxyfile' + +LINKS_NAVBAR1 = [ + (None, 'pages', [(None, 'about')]), + (None, 'namespaces', []), +] + +# Add your own navbar links using the code below. +# To find the valid link names, you can inspect the URL of a generated documentation site. + +# LINKS_NAVBAR1 = [ +# (None, 'pages', [(None, 'about')]), +# (None, 'namespaces', [(None, 'namespacegreeter')]), +# ] +# +# LINKS_NAVBAR2 = [ +# (None, 'annotated', [(None, 'classgreeter_1_1_greeter')]), +# (None, 'files', [(None, 'greeter_8h')]), +# ] diff --git a/documentation/pages/about.dox b/documentation/pages/about.dox new file mode 100644 index 0000000..8ca02c0 --- /dev/null +++ b/documentation/pages/about.dox @@ -0,0 +1,5 @@ +/** @page about About + @section doc ModernCppStarter Documentation + This is the auto-generated documentation for the initial project of the ModernCppStater. + It shows how we can use Doxygen to automatically build a browsable documentation for your projects. +*/ diff --git a/include/greeter/greeter.h b/include/greeter/greeter.h index e3ff923..77dfe3b 100644 --- a/include/greeter/greeter.h +++ b/include/greeter/greeter.h @@ -8,20 +8,20 @@ namespace greeter { enum class LanguageCode { EN, DE, ES, FR }; /** - * A class for saying hello in multiple languages + * @brief A class for saying hello in multiple languages */ class Greeter { std::string name; public: /** - * Creates a new greeter + * @brief Creates a new greeter * @param name the name to greet */ Greeter(std::string name); /** - * Creates a localized string containing the greeting + * @brief Creates a localized string containing the greeting * @param lang the language to greet in * @return a string containing the greeting */