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 <TheLartians@users.noreply.github.com>

documentation/CMakeLists.txt

@@ -12,25 +12,35 @@ CPMAddPackage(
 )
 
 CPMAddPackage(
-  NAME StableCoder-cmake-scripts
+  NAME MCSS
-  GITHUB_REPOSITORY StableCoder/cmake-scripts
+  DOWNLOAD_ONLY YES
-  GIT_TAG 3d2d5a9fb26f0ce24e3e4eaeeff686ec2ecfb3fb
+  # patched version until https://github.com/mosra/m.css/pull/171 is resolved
+  GITHUB_REPOSITORY TheLartians/m.css
+  GIT_TAG 1bf162b96d5bfefc9967a80cef138f1270ffa415
 )
 
-# ---- Doxygen ----
+# ---- Doxygen variables ----
-
-set(BUILD_DOCUMENTATION ON CACHE INTERNAL "")
-include(${StableCoder-cmake-scripts_SOURCE_DIR}/doxygen.cmake)
 
 # 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
+configure_file(
-build_docs(
+  ${CMAKE_CURRENT_LIST_DIR}/Doxyfile
-  TARGET_NAME GenerateDocs
+  ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-  DOXYFILE_PATH ${CMAKE_CURRENT_LIST_DIR}/Doxyfile
+)
-  OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen
+
-  PROCESS_DOXYFILE ON
+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}"
 )

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
-
+OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@
-# We don't want local paths in the documentation
-FULL_PATH_NAMES = NO
 
 # Use the README as a main page
 USE_MDFILE_AS_MAINPAGE = @DOXYGEN_PROJECT_ROOT@/README.md
 
-# Create nicer looking HTML
+# set relative include paths
-HTML_DYNAMIC_SECTIONS = YES
+FULL_PATH_NAMES = YES
-GENERATE_TREEVIEW = 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

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')]),
+# ]

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.
+*/

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
      */