From 6f0e8caf8de98686d27a5286d16ec7f5931166c2 Mon Sep 17 00:00:00 2001 From: Pascal Thomet Date: Sat, 16 May 2020 14:48:12 +0200 Subject: [PATCH 1/2] Add top src/ folder, with 2 target / add top include/ folder --- include/animals/animals.h | 10 ++++++++++ src/CMakeLists.txt | 3 +++ src/cat/CMakeLists.txt | 1 + {CatCutifier => src/cat/cat_cutifier}/CMakeLists.txt | 0 {CatCutifier => src/cat/cat_cutifier}/CatCutifier.cpp | 0 {CatCutifier => src/cat/cat_cutifier}/CatCutifier.h | 0 src/cat/cat_cutifier/internal/CatInternalHeader.h | 2 ++ src/dog/CMakeLists.txt | 2 ++ src/dog/dog_ugliflier/CMakeLists.txt | 4 ++++ src/dog/dog_ugliflier/DogUglifier.cpp | 4 ++++ src/dog/dog_ugliflier/DogUglifier.h | 11 +++++++++++ 11 files changed, 37 insertions(+) create mode 100644 include/animals/animals.h create mode 100644 src/CMakeLists.txt create mode 100644 src/cat/CMakeLists.txt rename {CatCutifier => src/cat/cat_cutifier}/CMakeLists.txt (100%) rename {CatCutifier => src/cat/cat_cutifier}/CatCutifier.cpp (100%) rename {CatCutifier => src/cat/cat_cutifier}/CatCutifier.h (100%) create mode 100644 src/cat/cat_cutifier/internal/CatInternalHeader.h create mode 100644 src/dog/CMakeLists.txt create mode 100644 src/dog/dog_ugliflier/CMakeLists.txt create mode 100644 src/dog/dog_ugliflier/DogUglifier.cpp create mode 100644 src/dog/dog_ugliflier/DogUglifier.h diff --git a/include/animals/animals.h b/include/animals/animals.h new file mode 100644 index 0000000..93bd658 --- /dev/null +++ b/include/animals/animals.h @@ -0,0 +1,10 @@ +namespace Animals +{ + enum Species + { + Cat, + Dog, + Cow + }; +} +#endif //CPP_DOCUMENTATION_EXAMPLE_ANIMAL_H diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt new file mode 100644 index 0000000..0df73b7 --- /dev/null +++ b/src/CMakeLists.txt @@ -0,0 +1,3 @@ +add_subdirectory(cat) +add_subdirectory(dog) + diff --git a/src/cat/CMakeLists.txt b/src/cat/CMakeLists.txt new file mode 100644 index 0000000..2ddbafa --- /dev/null +++ b/src/cat/CMakeLists.txt @@ -0,0 +1 @@ +add_subdirectory(cat_cutifier) diff --git a/CatCutifier/CMakeLists.txt b/src/cat/cat_cutifier/CMakeLists.txt similarity index 100% rename from CatCutifier/CMakeLists.txt rename to src/cat/cat_cutifier/CMakeLists.txt diff --git a/CatCutifier/CatCutifier.cpp b/src/cat/cat_cutifier/CatCutifier.cpp similarity index 100% rename from CatCutifier/CatCutifier.cpp rename to src/cat/cat_cutifier/CatCutifier.cpp diff --git a/CatCutifier/CatCutifier.h b/src/cat/cat_cutifier/CatCutifier.h similarity index 100% rename from CatCutifier/CatCutifier.h rename to src/cat/cat_cutifier/CatCutifier.h diff --git a/src/cat/cat_cutifier/internal/CatInternalHeader.h b/src/cat/cat_cutifier/internal/CatInternalHeader.h new file mode 100644 index 0000000..d7bc4a5 --- /dev/null +++ b/src/cat/cat_cutifier/internal/CatInternalHeader.h @@ -0,0 +1,2 @@ +// Haaders in this folder are considered internal, ans will not be part of the doc. +// See doc/CMakeLists.txt: subfolders internal/ details/ and private/ are ignored diff --git a/src/dog/CMakeLists.txt b/src/dog/CMakeLists.txt new file mode 100644 index 0000000..9a5ed47 --- /dev/null +++ b/src/dog/CMakeLists.txt @@ -0,0 +1,2 @@ +add_subdirectory(dog_ugliflier) + diff --git a/src/dog/dog_ugliflier/CMakeLists.txt b/src/dog/dog_ugliflier/CMakeLists.txt new file mode 100644 index 0000000..afa8862 --- /dev/null +++ b/src/dog/dog_ugliflier/CMakeLists.txt @@ -0,0 +1,4 @@ +add_library (DogUglifier "DogUglifier.cpp" "DogUglifier.h") +target_include_directories(DogUglifier PUBLIC .) + +# Should install library properly here, but I'm focusing on just the docs \ No newline at end of file diff --git a/src/dog/dog_ugliflier/DogUglifier.cpp b/src/dog/dog_ugliflier/DogUglifier.cpp new file mode 100644 index 0000000..d374f35 --- /dev/null +++ b/src/dog/dog_ugliflier/DogUglifier.cpp @@ -0,0 +1,4 @@ +#include "DogUglifier.h" + +void dog::make_ugly(){ +} \ No newline at end of file diff --git a/src/dog/dog_ugliflier/DogUglifier.h b/src/dog/dog_ugliflier/DogUglifier.h new file mode 100644 index 0000000..d4de9ba --- /dev/null +++ b/src/dog/dog_ugliflier/DogUglifier.h @@ -0,0 +1,11 @@ +#pragma once + +/** + An ugly dog +*/ +struct dog { + /** + Make this dog ugly + */ + void make_ugly(); +}; \ No newline at end of file From d54ef50c3cb1a8663a62f2f8c5e381293140a59d Mon Sep 17 00:00:00 2001 From: Pascal Thomet Date: Sat, 16 May 2020 14:51:28 +0200 Subject: [PATCH 2/2] Docs scripts: handle several targets --- CMakeLists.txt | 4 ++-- docs/CMakeLists.txt | 26 +++++++++++++++++--------- docs/Doxyfile.in | 4 ++-- docs/conf.py | 19 ++++++++++++------- docs/index.rst | 23 ++++++++++++++++++++++- 5 files changed, 55 insertions(+), 21 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index d1f904c..4b3d25e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,9 +1,9 @@ cmake_minimum_required (VERSION 3.8) -project ("CatCutifier") +project ("cpp-documentation-example") # Add the cmake folder so the FindSphinx module is found set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH}) -add_subdirectory ("CatCutifier") +add_subdirectory ("src") add_subdirectory ("docs") diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index a4f7629..0339c70 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,12 +1,8 @@ find_package(Doxygen REQUIRED) find_package(Sphinx REQUIRED) -# Find all the public headers -get_target_property(CAT_CUTIFIER_PUBLIC_HEADER_DIR CatCutifier INTERFACE_INCLUDE_DIRECTORIES) -file(GLOB_RECURSE CAT_CUTIFIER_PUBLIC_HEADERS - ${CAT_CUTIFIER_PUBLIC_HEADER_DIR}/*.h) - -set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/CatCutifier) +set(DOXYGEN_INPUT_DIR_SRC ${PROJECT_SOURCE_DIR}/src) +set(DOXYGEN_INPUT_DIR_INCLUDE ${PROJECT_SOURCE_DIR}/include) set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen) set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml) set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in) @@ -18,9 +14,20 @@ configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) # Doxygen won't create this for us file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) +# Find all the public headers +file(GLOB_RECURSE project_include_headers ${PROJECT_SOURCE_DIR}/include/*.h ${PROJECT_SOURCE_DIR}/include/*.hpp) +file(GLOB_RECURSE project_src_headers ${PROJECT_SOURCE_DIR}/src/*.h ${PROJECT_SOURCE_DIR}/src/*.hpp) +# Filter out headers files in src/**/internal/ details/ private/ subfolders +list(FILTER project_src_headers EXCLUDE REGEX "\/internal\/") +list(FILTER project_src_headers EXCLUDE REGEX "\/details\/") +list(FILTER project_src_headers EXCLUDE REGEX "\/private\/") +set(project_headers ${project_include_headers} ${project_src_headers}) +message("project_include_headers=${project_include_headers}") +message("project_headers=${project_headers}") + # Only regenerate Doxygen when the Doxyfile or public headers change add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE} - DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS} + DEPENDS ${project_include_headers} COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} COMMENT "Generating docs" @@ -29,6 +36,7 @@ add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE} # Nice named target so we can run the job easily add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE}) + set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}) set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx) set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html) @@ -41,10 +49,10 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE} COMMAND ${SPHINX_EXECUTABLE} -b html # Tell Breathe where to find the Doxygen output - -Dbreathe_projects.CatCutifier=${DOXYGEN_OUTPUT_DIR}/xml + -Dbreathe_projects.main_project=${DOXYGEN_OUTPUT_DIR}/xml ${SPHINX_SOURCE} ${SPHINX_BUILD} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - DEPENDS + DEPENDS # Other docs files you want to track should go here (or in some variable) ${CMAKE_CURRENT_SOURCE_DIR}/index.rst ${DOXYGEN_INDEX_FILE} diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index ac6b938..4b23b42 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -813,7 +813,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = "@DOXYGEN_INPUT_DIR@" +INPUT = "@DOXYGEN_INPUT_DIR_SRC@" "@DOXYGEN_INPUT_DIR_INCLUDE@" # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -888,7 +888,7 @@ FILE_PATTERNS = *.c \ # be searched for input files as well. # The default value is: NO. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a diff --git a/docs/conf.py b/docs/conf.py index 9c7eaa0..0e7d9d8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,12 +16,16 @@ import subprocess, os -def configureDoxyfile(input_dir, output_dir): +def configureDoxyfile(top_dir, output_dir): with open('Doxyfile.in', 'r') as file : filedata = file.read() - filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', input_dir) + input_dir_src = top_dir + "/src" + input_dir_include = top_dir + "/include" + + filedata = filedata.replace('@DOXYGEN_INPUT_DIR_SRC@', input_dir_src) + filedata = filedata.replace('@DOXYGEN_INPUT_DIR_INCLUDE@', input_dir_include) filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', output_dir) with open('Doxyfile', 'w') as file: @@ -32,16 +36,16 @@ def configureDoxyfile(input_dir, output_dir): breathe_projects = {} if read_the_docs_build: - input_dir = '../CatCutifier' + top_dir = '../' output_dir = 'build' - configureDoxyfile(input_dir, output_dir) + configureDoxyfile(top_dir, output_dir) subprocess.call('doxygen', shell=True) - breathe_projects['CatCutifier'] = output_dir + '/xml' + breathe_projects['main_project'] = output_dir + '/xml' # -- Project information ----------------------------------------------------- -project = 'CatCutifier' +project = 'cat_cutifier' copyright = '2019, Simon Brand' author = 'Simon Brand' @@ -79,4 +83,5 @@ def configureDoxyfile(input_dir, output_dir): html_static_path = ['_static'] # Breathe Configuration -breathe_default_project = "CatCutifier" \ No newline at end of file +breathe_default_project = "main_project" + diff --git a/docs/index.rst b/docs/index.rst index bad13d1..a64be7a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,5 +15,26 @@ Welcome to CatCutifier's documentation! Docs ==== +Animals +------- + +First we have some animals + +.. doxygennamespace:: Animals + :members: + +Cats +---- + +Enter the cats + .. doxygenstruct:: cat - :members: \ No newline at end of file + :members: + +Dogs +---- + +And the dogs + +.. doxygenstruct:: dog + :members: