From 05b70c9b00d49baf28638f07111f8571c5eade40 Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 11:45:40 +0200 Subject: [PATCH 1/8] Add a script for documentation --- .github/workflows/ubuntu_2204_documentation_pipeline.yml | 2 +- scripts/document.sh | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100755 scripts/document.sh diff --git a/.github/workflows/ubuntu_2204_documentation_pipeline.yml b/.github/workflows/ubuntu_2204_documentation_pipeline.yml index 162d3d9..706f671 100644 --- a/.github/workflows/ubuntu_2204_documentation_pipeline.yml +++ b/.github/workflows/ubuntu_2204_documentation_pipeline.yml @@ -12,5 +12,5 @@ jobs: - name: Configure run: ./scripts/configure.sh - name: Make documentation - run: cd build && make documentation + run: ./scripts/documentation.sh diff --git a/scripts/document.sh b/scripts/document.sh new file mode 100755 index 0000000..cc164e1 --- /dev/null +++ b/scripts/document.sh @@ -0,0 +1,5 @@ +#!/bin/bash +set -euxo pipefail +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +cd "$DIR"/../build || exit 1 +make documentation From 380060357edabf40d24183e76ffedbf45deabb2e Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 12:12:58 +0000 Subject: [PATCH 2/8] Add doxygen --- .devcontainer/Dockerfile | 11 +++-- ...> setup_build_environment_on_ubuntu_22.sh} | 2 +- ..._documentation_environment_on_ubuntu_22.sh | 7 ++++ .../workflows/ubuntu_2204_build_pipeline.yml | 2 +- .../ubuntu_2204_documentation_pipeline.yml | 2 +- .gitignore | 1 + documentation/CMakeLists.txt | 23 ++++++++--- documentation/code-documentation.doxygen | 40 +++++++++++++++++++ .../benchmark/probe_benchmark.cpp | 3 ++ project/probelibrary/include/probe.h | 6 +++ project/probelibrary/tests/unit_test.cpp | 7 ++++ scripts/document.sh | 3 +- 12 files changed, 93 insertions(+), 14 deletions(-) rename .devcontainer/{setup_environment_on_ubuntu_22.sh => setup_build_environment_on_ubuntu_22.sh} (96%) create mode 100755 .devcontainer/setup_documentation_environment_on_ubuntu_22.sh create mode 100644 documentation/code-documentation.doxygen diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 04e7b53..fee940f 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,11 +1,14 @@ # Base image FROM mcr.microsoft.com/devcontainers/base:jammy -COPY setup_environment_on_ubuntu_22.sh . +COPY setup_build_environment_on_ubuntu_22.sh . +COPY setup_documentation_environment_on_ubuntu_22.sh . COPY requirements.txt . -RUN chmod +x setup_environment_on_ubuntu_22.sh -RUN ./setup_environment_on_ubuntu_22.sh +RUN chmod +x setup_build_environment_on_ubuntu_22.sh +RUN chmod +x setup_documentation_environment_on_ubuntu_22.sh +RUN ./setup_build_environment_on_ubuntu_22.sh +RUN ./setup_documentation_environment_on_ubuntu_22.sh WORKDIR /workspace -CMD ["/bin/bash"] \ No newline at end of file +CMD ["/bin/bash"] diff --git a/.devcontainer/setup_environment_on_ubuntu_22.sh b/.devcontainer/setup_build_environment_on_ubuntu_22.sh similarity index 96% rename from .devcontainer/setup_environment_on_ubuntu_22.sh rename to .devcontainer/setup_build_environment_on_ubuntu_22.sh index 054f1f7..e3df438 100755 --- a/.devcontainer/setup_environment_on_ubuntu_22.sh +++ b/.devcontainer/setup_build_environment_on_ubuntu_22.sh @@ -4,7 +4,7 @@ DEBIAN_FRONTEND=noninteractive DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR" sudo apt-get update -sudo apt-get install -y curl nano cmake gcc gcovr python3 python3-pip git texlive-full biber +sudo apt-get install -y curl nano cmake gcc gcovr python3 python3-pip git python3 -m pip install -r requirements.txt diff --git a/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh new file mode 100755 index 0000000..9171209 --- /dev/null +++ b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh @@ -0,0 +1,7 @@ +#!/bin/bash +set -euxo pipefail +DEBIAN_FRONTEND=noninteractive +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +cd "$DIR" +sudo apt-get update +sudo apt-get install -y cmake git texlive-full biber doxygen graphviz diff --git a/.github/workflows/ubuntu_2204_build_pipeline.yml b/.github/workflows/ubuntu_2204_build_pipeline.yml index 6a0b5a7..5d626c8 100644 --- a/.github/workflows/ubuntu_2204_build_pipeline.yml +++ b/.github/workflows/ubuntu_2204_build_pipeline.yml @@ -8,7 +8,7 @@ jobs: steps: - uses: actions/checkout@v1 - name: Install development dependencies - run: ./.devcontainer/setup_environment_on_ubuntu_22.sh + run: ./.devcontainer/setup_build_environment_on_ubuntu_22.sh - name: Check formating run: ./scripts/format.sh - name: Configure diff --git a/.github/workflows/ubuntu_2204_documentation_pipeline.yml b/.github/workflows/ubuntu_2204_documentation_pipeline.yml index 706f671..1642162 100644 --- a/.github/workflows/ubuntu_2204_documentation_pipeline.yml +++ b/.github/workflows/ubuntu_2204_documentation_pipeline.yml @@ -8,7 +8,7 @@ jobs: steps: - uses: actions/checkout@v1 - name: Install development dependencies - run: ./.devcontainer/setup_environment_on_ubuntu_22.sh + run: ./.devcontainer/setup_documentation_environment_on_ubuntu_22.sh - name: Configure run: ./scripts/configure.sh - name: Make documentation diff --git a/.gitignore b/.gitignore index fe577ee..5b95993 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ build/* +output/* documentation/*.bbl documentation/*.blg diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 281dbd5..aa5654c 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -1,16 +1,27 @@ INCLUDE (CreateLatexDocumentation) SET (requirements_documents "requirements_document") -SET (SOFTWARE_INTERN_MAIN_TEX ${requirements_documents}.tex) -SET (SOFTWARE_INTERN_RESOURCES_FILES +SET (REQUIREMENTS_DOCUMENT_MAIN_TEX ${requirements_documents}.tex) +SET (REQUIREMENTS_DOCUMENTS_RESOURCES_FILES ${CMAKE_CURRENT_SOURCE_DIR}/resources/project_or_company_logo.png) -SET (SOFTWARE_INTERN_BIBLIOGRAPHY ${CMAKE_CURRENT_SOURCE_DIR}/library.bib) +SET (REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY + ${CMAKE_CURRENT_SOURCE_DIR}/library.bib) CREATELATEXDOCUMENTAION ( - "${requirements_documents}" "${SOFTWARE_INTERN_MAIN_TEX}" - "${SOFTWARE_INTERN_RESOURCES_FILES}" "${SOFTWARE_INTERN_BIBLIOGRAPHY}") + "${requirements_documents}" "${REQUIREMENTS_DOCUMENT_MAIN_TEX}" + "${REQUIREMENTS_DOCUMENTS_RESOURCES_FILES}" + "${REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY}") ADD_CUSTOM_TARGET ( - documentation + requirements_engineering DEPENDS ${requirements_documents} COMMENT "Building requirements documentation") + +SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_BINARY_DIR}/documentation") +SET (ENV{DOCUMENTATION_OUTPUT_FOLDER} ${DOCUMENTATION_OUTPUT_FOLDER}) +FILE (MAKE_DIRECTORY ${DOCUMENTATION_OUTPUT_FOLDER}) +ADD_CUSTOM_TARGET ( + code_documentation + COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} + COMMENT "Building code documentation") diff --git a/documentation/code-documentation.doxygen b/documentation/code-documentation.doxygen new file mode 100644 index 0000000..adb46d4 --- /dev/null +++ b/documentation/code-documentation.doxygen @@ -0,0 +1,40 @@ +# Doxyfile + +# Set the project name +PROJECT_NAME = My Project + +PROJECT_LOGO = documentation/resources/project_or_company_logo.png + +# Set the project version + + +# Set the output directory for the generated documentation +OUTPUT_DIRECTORY = $(DOCUMENTATION_OUTPUT_FOLDER)/code-documentation/ +CREATE_SUBDIRS = YES + +# Set the input directories for the source code +INPUT = project +RECURSIVE = YES + +# Set the file patterns to include in the documentation +FILE_PATTERNS = *.cpp *.h + +# Enable HTML output +GENERATE_HTML = YES + +# Set the HTML output directory +HTML_OUTPUT = html + +# Enable the generation of a compound index + + +# Enable the generation of a search index + + +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST = YES + + + +GENERATE_LATEX = YES diff --git a/project/probelibrary/benchmark/probe_benchmark.cpp b/project/probelibrary/benchmark/probe_benchmark.cpp index 33044c4..62923c8 100644 --- a/project/probelibrary/benchmark/probe_benchmark.cpp +++ b/project/probelibrary/benchmark/probe_benchmark.cpp @@ -1,3 +1,6 @@ +/*! \file probe_benchmark.cpp + * \brief Benchmark runtime of probe library + */ #include #include diff --git a/project/probelibrary/include/probe.h b/project/probelibrary/include/probe.h index 388c7fc..bdab658 100644 --- a/project/probelibrary/include/probe.h +++ b/project/probelibrary/include/probe.h @@ -1,3 +1,9 @@ +/*! \file probe.h +\brief Example library with a single free function (probe) +*/ #include +/*! \fn void Probe + * \brief Probe function + */ void Probe(); diff --git a/project/probelibrary/tests/unit_test.cpp b/project/probelibrary/tests/unit_test.cpp index b9c61db..1da8e8f 100644 --- a/project/probelibrary/tests/unit_test.cpp +++ b/project/probelibrary/tests/unit_test.cpp @@ -1,6 +1,13 @@ +/*! \file unit_test.cpp +\brief unit tests of probe library +*/ + #include #include +/*! \test ProbeSanity + * \brief Check that the Probe function does not throw + */ TEST(ProbeSanity, NoThrow) { EXPECT_NO_THROW(Probe()); } diff --git a/scripts/document.sh b/scripts/document.sh index cc164e1..c4e846f 100755 --- a/scripts/document.sh +++ b/scripts/document.sh @@ -2,4 +2,5 @@ set -euxo pipefail DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR"/../build || exit 1 -make documentation +make requirements_engineering +make code_documentation From 6ad89f0918baa2cc33f9e9ec5fca6f8da5ebe603 Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 13:24:52 +0000 Subject: [PATCH 3/8] Fix cmake module that create latex document --- cmake_modules/CreateLatexDocument.cmake | 81 +++++++++++++++++ cmake_modules/CreateLatexDocumentation.cmake | 91 -------------------- documentation/CMakeLists.txt | 8 +- documentation/requirements_document.tex | 2 +- 4 files changed, 86 insertions(+), 96 deletions(-) create mode 100644 cmake_modules/CreateLatexDocument.cmake delete mode 100644 cmake_modules/CreateLatexDocumentation.cmake diff --git a/cmake_modules/CreateLatexDocument.cmake b/cmake_modules/CreateLatexDocument.cmake new file mode 100644 index 0000000..f53a3ba --- /dev/null +++ b/cmake_modules/CreateLatexDocument.cmake @@ -0,0 +1,81 @@ +MACRO (CreateLatexDocument _name _texsrc _resources _bibliography) + FIND_PROGRAM (BIBER biber) + FIND_PROGRAM (PDFLATEX pdflatex) + FIND_PROGRAM (MAKEINDEX makeindex) + + IF (${BIBER}-NOTFOUND) + MESSAGE (FATAL_ERROR "biber not found!") + ENDIF () + IF (${PDFLATEX}-NOTFOUND) + MESSAGE (FATAL_ERROR "pdflatex not found!") + ENDIF () + IF (${MAKEINDEX}-NOTFOUND) + MESAGE (FATAL_ERROR "pdflatex not found!") + ENDIF () + SET (_output_folder "${CMAKE_CURRENT_BINARY_DIR}/${_name}/") + FILE (MAKE_DIRECTORY ${_output_folder}) + + ADD_CUSTOM_TARGET ( + ${_name} + DEPENDS ${_output_folder}/${_name}.pdf + SOURCES ${_texsrcs}) + + ADD_CUSTOM_COMMAND ( + OUTPUT ${_output_folder}/${_name}.bcf ${_output_folder}/${_name}.idx + ${_output_folder}/${_name}.nlo + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + DEPENDS ${_texsrcs} ${_resources} + # COMMAND cmake -E copy ${_resources} ${_output_folder} + COMMAND cmake -E copy ${_texsrc} ${_output_folder} + VERBATIM + COMMAND ${PDFLATEX} -output-directory ${_output_folder} + ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex + COMMENT "First pass software internal documentation") + + # Runnig biber on the .blg created by the firs pass of pdflatex + ADD_CUSTOM_COMMAND ( + OUTPUT ${_output_folder}/${_name}.blg + COMMENT "Running ${BIBER} on ${_output_folder}/${_name}.bcf" + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + COMMAND ${BIBER} --input-directory ${_output_folder} --output-directory + ${_output_folder} ${_name}.bcf + DEPENDS ${_output_folder}/${_name}.bcf ${_bibliography}) + + # Running the make_index + SET ( + _index_output + "${CMAKE_CURRENT_BINARY_DIR}/${_name}.ilg ${_output_folder}/${_name}.ind") + ADD_CUSTOM_COMMAND ( + OUTPUT ${_index_output} + DEPENDS ${_output_folder}/${_name}.idx + COMMENT "Runnning ${MAKEINDEX} on ${_output_folder}/${_name}.idx" + WORKING_DIRECTORY ${_output_folder} + COMMAND ${MAKEINDEX} ${_name}.idx) + + # Running make_index for glossary and acronyms + SET ( + _glossary_output + "${_output_folder}/${_name}.nls ${_output_folder}/${_name}.ilg ${_output_folder}/${_name}.gls ${_output_folder}/${_name}.glo ${_output_folder}/${_name}.acr ${_output_folder}/${_name}.acn" + ) + ADD_CUSTOM_COMMAND ( + OUTPUT ${_glossary_output} + DEPENDS ${_output_folder}/${_name}.nlo + WORKING_DIRECTORY ${_output_folder} + COMMAND ${MAKEINDEX} ${_name}.nlo -s nomencl.ist -o ${_name}.nls + COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.glg -o ${_name}.gls + ${_name}.glo + COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.alg -o ${_name}.acr + ${_name}.acn) + + # The final pass + ADD_CUSTOM_COMMAND ( + OUTPUT ${_output_folder}/${_name}.pdf + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + DEPENDS ${_output_folder}/${_name}.blg ${_index_output} ${_glossary_output} + # COMMAND cmake -E copy ${_resources} ${_output_folder} + VERBATIM + COMMAND ${PDFLATEX} -output-directory ${_output_folder} + ${_output_folder}/${_name}.tex + COMMENT "Building software internal documentation") + +ENDMACRO () diff --git a/cmake_modules/CreateLatexDocumentation.cmake b/cmake_modules/CreateLatexDocumentation.cmake deleted file mode 100644 index 5e4987a..0000000 --- a/cmake_modules/CreateLatexDocumentation.cmake +++ /dev/null @@ -1,91 +0,0 @@ -MACRO (CreateLatexDocumentaion _name _texsrc _resources _bibliography) - FIND_PROGRAM (BIBER biber) - FIND_PROGRAM (PDFLATEX pdflatex) - FIND_PROGRAM (MAKEINDEX makeindex) - - # message(FATAL_ERROR ${BIBER}) - IF (${BIBER}-NOTFOUND) - MESSAGE ( - FATAL_ERROR - "biber not found! run install-doc-dep.sh to install documentation build dependencies!" - ) - ENDIF () - IF (${PDFLATEX}-NOTFOUND) - MESSAGE ( - FATAL_ERROR - "pdflatex not found! run install-doc-dep.sh to install documentation build dependencies!" - ) - ENDIF () - IF (${MAKEINDEX}-NOTFOUND) - MESAGE ( - FATAL_ERROR - "pdflatex not found! run install-doc-dep.sh to install documentation build dependencies!" - ) - ENDIF () - - ADD_CUSTOM_TARGET ( - ${_name} - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_name}.pdf - SOURCES ${_texsrcs}) - - ADD_CUSTOM_COMMAND ( - OUTPUT - ${CMAKE_CURRENT_BINARY_DIR}/${_name}.bcf - ${CMAKE_CURRENT_BINARY_DIR}/${_name}.idx - ${CMAKE_CURRENT_BINARY_DIR}/${_name}.nlo - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - DEPENDS ${_texsrcs} ${_resources} - COMMAND cmake -E copy ${_resources} ${CMAKE_CURRENT_BINARY_DIR} - VERBATIM - COMMAND ${PDFLATEX} -output-directory ${CMAKE_CURRENT_BINARY_DIR} - ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex - COMMENT "First pass software internal documentation") - - # Runnig biber on the .blg created by the firs pass of pdflatex - ADD_CUSTOM_COMMAND ( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${_name}.blg - COMMENT "Running ${BIBER} on ${CMAKE_CURRENT_BINARY_DIR}/${_name}.bcf" - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - COMMAND ${BIBER} --input-directory ${CMAKE_CURRENT_BINARY_DIR} ${_name}.bcf - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_name}.bcf ${_bibliography}) - - # Running the make_index - SET ( - _index_output - "${CMAKE_CURRENT_BINARY_DIR}/${_name}.ilg ${CMAKE_CURRENT_BINARY_DIR}/${_name}.ind" - ) - ADD_CUSTOM_COMMAND ( - OUTPUT ${_index_output} - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_name}.idx - COMMENT "Runnning ${MAKEINDEX} on ${CMAKE_CURRENT_BINARY_DIR}/${_name}.idx" - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMAND ${MAKEINDEX} ${_name}.idx) - - # Running make_index for glossary and acronyms - SET ( - _glossary_output - "${CMAKE_CURRENT_BINARY_DIR}/${_name}.nls ${CMAKE_CURRENT_BINARY_DIR}/${_name}.ilg ${CMAKE_CURRENT_BINARY_DIR}/${_name}.gls ${CMAKE_CURRENT_BINARY_DIR}/${_name}.glo ${CMAKE_CURRENT_BINARY_DIR}/${_name}.acr ${CMAKE_CURRENT_BINARY_DIR}/${_name}.acn" - ) - ADD_CUSTOM_COMMAND ( - OUTPUT ${_glossary_output} - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_name}.nlo - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMAND ${MAKEINDEX} ${_name}.nlo -s nomencl.ist -o ${_name}.nls - COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.glg -o ${_name}.gls - ${_name}.glo - COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.alg -o ${_name}.acr - ${_name}.acn) - - # The final pass - ADD_CUSTOM_COMMAND ( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${_name}.pdf - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${_name}.blg ${_index_output} - ${_glossary_output} - COMMAND cmake -E copy ${_resources} ${CMAKE_CURRENT_BINARY_DIR} - VERBATIM - COMMAND ${PDFLATEX} -output-directory ${CMAKE_CURRENT_BINARY_DIR} - ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex - COMMENT "Building software internal documentation") - -ENDMACRO () diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index aa5654c..c8d7b32 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -1,4 +1,4 @@ -INCLUDE (CreateLatexDocumentation) +INCLUDE (CreateLatexDocument) SET (requirements_documents "requirements_document") SET (REQUIREMENTS_DOCUMENT_MAIN_TEX ${requirements_documents}.tex) @@ -7,7 +7,7 @@ SET (REQUIREMENTS_DOCUMENTS_RESOURCES_FILES SET (REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY ${CMAKE_CURRENT_SOURCE_DIR}/library.bib) -CREATELATEXDOCUMENTAION ( +CREATELATEXDOCUMENT ( "${requirements_documents}" "${REQUIREMENTS_DOCUMENT_MAIN_TEX}" "${REQUIREMENTS_DOCUMENTS_RESOURCES_FILES}" "${REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY}") @@ -17,9 +17,9 @@ ADD_CUSTOM_TARGET ( DEPENDS ${requirements_documents} COMMENT "Building requirements documentation") -SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_BINARY_DIR}/documentation") +SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_CURRENT_BINARY_DIR}") SET (ENV{DOCUMENTATION_OUTPUT_FOLDER} ${DOCUMENTATION_OUTPUT_FOLDER}) -FILE (MAKE_DIRECTORY ${DOCUMENTATION_OUTPUT_FOLDER}) +# FILE (MAKE_DIRECTORY ${DOCUMENTATION_OUTPUT_FOLDER}) ADD_CUSTOM_TARGET ( code_documentation COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen diff --git a/documentation/requirements_document.tex b/documentation/requirements_document.tex index 371471b..5a2a9a0 100644 --- a/documentation/requirements_document.tex +++ b/documentation/requirements_document.tex @@ -45,7 +45,7 @@ \section{The first section} \newacronym[longplural={First Acronyms}]{FAlabel}{FA}{First Acronym} This is how to use the \gls{FAlabel}. And now making a second use of \gls{FAlabel}. -\cite{uncleDT} +\cite{fooAuthor} \begin{figure}[ht] \centering From 8651be345923ed6e9b2b2400c092b11ca9dc5c89 Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 14:05:19 +0000 Subject: [PATCH 4/8] Fix dependencies in doxygen documentation --- ..._documentation_environment_on_ubuntu_22.sh | 2 +- documentation/CMakeLists.txt | 24 ++++++++++--------- scripts/document.sh | 2 +- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh index 9171209..b61f903 100755 --- a/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh +++ b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh @@ -4,4 +4,4 @@ DEBIAN_FRONTEND=noninteractive DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR" sudo apt-get update -sudo apt-get install -y cmake git texlive-full biber doxygen graphviz +sudo apt-get install -y cmake git texlive-full biber doxygen graphviz makefile2graph diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index c8d7b32..abd4cb5 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -1,27 +1,29 @@ INCLUDE (CreateLatexDocument) -SET (requirements_documents "requirements_document") -SET (REQUIREMENTS_DOCUMENT_MAIN_TEX ${requirements_documents}.tex) +SET (requirements_document "requirements_document") +SET (REQUIREMENTS_DOCUMENT_MAIN_TEX ${requirements_document}.tex) SET (REQUIREMENTS_DOCUMENTS_RESOURCES_FILES ${CMAKE_CURRENT_SOURCE_DIR}/resources/project_or_company_logo.png) SET (REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY ${CMAKE_CURRENT_SOURCE_DIR}/library.bib) CREATELATEXDOCUMENT ( - "${requirements_documents}" "${REQUIREMENTS_DOCUMENT_MAIN_TEX}" + "${requirements_document}" "${REQUIREMENTS_DOCUMENT_MAIN_TEX}" "${REQUIREMENTS_DOCUMENTS_RESOURCES_FILES}" "${REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY}") -ADD_CUSTOM_TARGET ( - requirements_engineering - DEPENDS ${requirements_documents} - COMMENT "Building requirements documentation") - +# Doxygen documentation SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_CURRENT_BINARY_DIR}") SET (ENV{DOCUMENTATION_OUTPUT_FOLDER} ${DOCUMENTATION_OUTPUT_FOLDER}) -# FILE (MAKE_DIRECTORY ${DOCUMENTATION_OUTPUT_FOLDER}) -ADD_CUSTOM_TARGET ( - code_documentation +ADD_CUSTOM_COMMAND ( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/code-documentation/html/index.html + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + VERBATIM COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Building code documentation") +ADD_CUSTOM_TARGET ( + code_documentation + SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + COMMENT "Target code documentation" + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code-documentation/html/index.html) diff --git a/scripts/document.sh b/scripts/document.sh index c4e846f..2040408 100755 --- a/scripts/document.sh +++ b/scripts/document.sh @@ -2,5 +2,5 @@ set -euxo pipefail DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR"/../build || exit 1 -make requirements_engineering +make requirements_document make code_documentation From d973e6e57a2f7369cf9c6b3bad416afde65ad366 Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 15:15:48 +0000 Subject: [PATCH 5/8] Fix dependencies when creating latex document --- cmake_modules/CreateLatexDocument.cmake | 62 ++++--------------- documentation/CMakeLists.txt | 10 +-- ...ion.doxygen => code_documentation.doxygen} | 2 +- documentation/requirements_document.tex | 2 +- 4 files changed, 19 insertions(+), 57 deletions(-) rename documentation/{code-documentation.doxygen => code_documentation.doxygen} (92%) diff --git a/cmake_modules/CreateLatexDocument.cmake b/cmake_modules/CreateLatexDocument.cmake index f53a3ba..09efe5a 100644 --- a/cmake_modules/CreateLatexDocument.cmake +++ b/cmake_modules/CreateLatexDocument.cmake @@ -18,64 +18,26 @@ MACRO (CreateLatexDocument _name _texsrc _resources _bibliography) ADD_CUSTOM_TARGET ( ${_name} DEPENDS ${_output_folder}/${_name}.pdf - SOURCES ${_texsrcs}) + SOURCES ${_texsrc}) ADD_CUSTOM_COMMAND ( - OUTPUT ${_output_folder}/${_name}.bcf ${_output_folder}/${_name}.idx - ${_output_folder}/${_name}.nlo + OUTPUT ${_output_folder}/${_name}.pdf + DEPENDS ${_texsrc} ${_resources} ${_bibliography} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - DEPENDS ${_texsrcs} ${_resources} - # COMMAND cmake -E copy ${_resources} ${_output_folder} - COMMAND cmake -E copy ${_texsrc} ${_output_folder} + COMMENT "Generating ${_name}" VERBATIM COMMAND ${PDFLATEX} -output-directory ${_output_folder} ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex - COMMENT "First pass software internal documentation") - - # Runnig biber on the .blg created by the firs pass of pdflatex - ADD_CUSTOM_COMMAND ( - OUTPUT ${_output_folder}/${_name}.blg - COMMENT "Running ${BIBER} on ${_output_folder}/${_name}.bcf" - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} COMMAND ${BIBER} --input-directory ${_output_folder} --output-directory ${_output_folder} ${_name}.bcf - DEPENDS ${_output_folder}/${_name}.bcf ${_bibliography}) - - # Running the make_index - SET ( - _index_output - "${CMAKE_CURRENT_BINARY_DIR}/${_name}.ilg ${_output_folder}/${_name}.ind") - ADD_CUSTOM_COMMAND ( - OUTPUT ${_index_output} - DEPENDS ${_output_folder}/${_name}.idx - COMMENT "Runnning ${MAKEINDEX} on ${_output_folder}/${_name}.idx" - WORKING_DIRECTORY ${_output_folder} - COMMAND ${MAKEINDEX} ${_name}.idx) - - # Running make_index for glossary and acronyms - SET ( - _glossary_output - "${_output_folder}/${_name}.nls ${_output_folder}/${_name}.ilg ${_output_folder}/${_name}.gls ${_output_folder}/${_name}.glo ${_output_folder}/${_name}.acr ${_output_folder}/${_name}.acn" - ) - ADD_CUSTOM_COMMAND ( - OUTPUT ${_glossary_output} - DEPENDS ${_output_folder}/${_name}.nlo - WORKING_DIRECTORY ${_output_folder} - COMMAND ${MAKEINDEX} ${_name}.nlo -s nomencl.ist -o ${_name}.nls - COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.glg -o ${_name}.gls - ${_name}.glo - COMMAND ${MAKEINDEX} -s ${_name}.ist -t ${_name}.alg -o ${_name}.acr - ${_name}.acn) - - # The final pass - ADD_CUSTOM_COMMAND ( - OUTPUT ${_output_folder}/${_name}.pdf - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - DEPENDS ${_output_folder}/${_name}.blg ${_index_output} ${_glossary_output} - # COMMAND cmake -E copy ${_resources} ${_output_folder} - VERBATIM + COMMAND cd ${_output_folder} && ${MAKEINDEX} ${_name}.idx + COMMAND cd ${_output_folder} && ${MAKEINDEX} ${_name}.nlo -s nomencl.ist -o + ${_name}.nls + COMMAND cd ${_output_folder} && ${MAKEINDEX} -s ${_name}.ist -t ${_name}.glg + -o ${_name}.gls ${_name}.glo + COMMAND cd ${_output_folder} && ${MAKEINDEX} -s ${_name}.ist -t ${_name}.alg + -o ${_name}.acr ${_name}.acn COMMAND ${PDFLATEX} -output-directory ${_output_folder} - ${_output_folder}/${_name}.tex - COMMENT "Building software internal documentation") + ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex) ENDMACRO () diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index abd4cb5..5ccd3cd 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -16,14 +16,14 @@ CREATELATEXDOCUMENT ( SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_CURRENT_BINARY_DIR}") SET (ENV{DOCUMENTATION_OUTPUT_FOLDER} ${DOCUMENTATION_OUTPUT_FOLDER}) ADD_CUSTOM_COMMAND ( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/code-documentation/html/index.html - DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/code_documentation/html/index.html + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen VERBATIM - COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Building code documentation") ADD_CUSTOM_TARGET ( code_documentation - SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code-documentation.doxygen + SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen COMMENT "Target code documentation" - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code-documentation/html/index.html) + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code_documentation/html/index.html) diff --git a/documentation/code-documentation.doxygen b/documentation/code_documentation.doxygen similarity index 92% rename from documentation/code-documentation.doxygen rename to documentation/code_documentation.doxygen index adb46d4..b48ad4e 100644 --- a/documentation/code-documentation.doxygen +++ b/documentation/code_documentation.doxygen @@ -9,7 +9,7 @@ PROJECT_LOGO = documentation/resources/project_or_company_logo.png # Set the output directory for the generated documentation -OUTPUT_DIRECTORY = $(DOCUMENTATION_OUTPUT_FOLDER)/code-documentation/ +OUTPUT_DIRECTORY = $(DOCUMENTATION_OUTPUT_FOLDER)/code_documentation/ CREATE_SUBDIRS = YES # Set the input directories for the source code diff --git a/documentation/requirements_document.tex b/documentation/requirements_document.tex index 5a2a9a0..f563f22 100644 --- a/documentation/requirements_document.tex +++ b/documentation/requirements_document.tex @@ -54,7 +54,7 @@ \section{The first section} \label{reference} \end{figure} -The first equation is referenced as \ref{eq:eqFirstequation} +The first equation is referenced as \ref{eq:eqFirstequation}. \begin{equation} S~=~\Pi R^2 \label{eq:eqFirstequation} From 692ae929a8a46ef306e26e640cfe56027c0cfa6d Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 15:41:42 +0000 Subject: [PATCH 6/8] Add conan in the documentation pipeline for configuring --- .devcontainer/setup_documentation_environment_on_ubuntu_22.sh | 1 + .github/workflows/ubuntu_2204_documentation_pipeline.yml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh index b61f903..ca4e537 100755 --- a/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh +++ b/.devcontainer/setup_documentation_environment_on_ubuntu_22.sh @@ -5,3 +5,4 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$DIR" sudo apt-get update sudo apt-get install -y cmake git texlive-full biber doxygen graphviz makefile2graph +python3 -m pip install -r requirements.txt diff --git a/.github/workflows/ubuntu_2204_documentation_pipeline.yml b/.github/workflows/ubuntu_2204_documentation_pipeline.yml index 1642162..6abf3c2 100644 --- a/.github/workflows/ubuntu_2204_documentation_pipeline.yml +++ b/.github/workflows/ubuntu_2204_documentation_pipeline.yml @@ -12,5 +12,5 @@ jobs: - name: Configure run: ./scripts/configure.sh - name: Make documentation - run: ./scripts/documentation.sh + run: ./scripts/document.sh From 4237cbfddb3c0ad9f5a58bebc05c33d1327f443a Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Wed, 8 May 2024 16:44:44 +0000 Subject: [PATCH 7/8] Fix doxygen target not running on CI --- documentation/CMakeLists.txt | 11 +++++------ ...entation.doxygen => code_documentation.doxygen.in} | 2 +- 2 files changed, 6 insertions(+), 7 deletions(-) rename documentation/{code_documentation.doxygen => code_documentation.doxygen.in} (96%) diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 5ccd3cd..fa4c89f 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -13,17 +13,16 @@ CREATELATEXDOCUMENT ( "${REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY}") # Doxygen documentation -SET (DOCUMENTATION_OUTPUT_FOLDER "${CMAKE_CURRENT_BINARY_DIR}") -SET (ENV{DOCUMENTATION_OUTPUT_FOLDER} ${DOCUMENTATION_OUTPUT_FOLDER}) +CONFIGURE_FILE (${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen.in + ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen) ADD_CUSTOM_COMMAND ( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/code_documentation/html/index.html - DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen VERBATIM - COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen + COMMAND doxygen ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Building code documentation") ADD_CUSTOM_TARGET ( code_documentation - SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen - COMMENT "Target code documentation" + SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen.in DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code_documentation/html/index.html) diff --git a/documentation/code_documentation.doxygen b/documentation/code_documentation.doxygen.in similarity index 96% rename from documentation/code_documentation.doxygen rename to documentation/code_documentation.doxygen.in index b48ad4e..f48afe6 100644 --- a/documentation/code_documentation.doxygen +++ b/documentation/code_documentation.doxygen.in @@ -1,7 +1,7 @@ # Doxyfile # Set the project name -PROJECT_NAME = My Project +PROJECT_NAME = ProjectName PROJECT_LOGO = documentation/resources/project_or_company_logo.png From caaec6be68ee5d684cff3d24cadae45aa3dbd495 Mon Sep 17 00:00:00 2001 From: Maxime Haselbauer Date: Fri, 10 May 2024 16:06:59 +0000 Subject: [PATCH 8/8] Fix doxygen generation --- documentation/CMakeLists.txt | 2 +- documentation/code_documentation.doxygen.in | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index fa4c89f..4ed1a2b 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -20,7 +20,7 @@ ADD_CUSTOM_COMMAND ( DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen VERBATIM COMMAND doxygen ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen - WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Building code documentation") ADD_CUSTOM_TARGET ( code_documentation diff --git a/documentation/code_documentation.doxygen.in b/documentation/code_documentation.doxygen.in index f48afe6..7b68c80 100644 --- a/documentation/code_documentation.doxygen.in +++ b/documentation/code_documentation.doxygen.in @@ -3,17 +3,17 @@ # Set the project name PROJECT_NAME = ProjectName -PROJECT_LOGO = documentation/resources/project_or_company_logo.png +PROJECT_LOGO = @CMAKE_SOURCE_DIRECTORY@/documentation/resources/project_or_company_logo.png # Set the project version # Set the output directory for the generated documentation -OUTPUT_DIRECTORY = $(DOCUMENTATION_OUTPUT_FOLDER)/code_documentation/ +OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/code_documentation/ CREATE_SUBDIRS = YES # Set the input directories for the source code -INPUT = project +INPUT = @CMAKE_SOURCE_DIR@/project RECURSIVE = YES # Set the file patterns to include in the documentation