Merge pull request #3 from renn0xtek9/add-documentation

add documentation

.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"]
+CMD ["/bin/bash"]

.devcontainer/setup_environment_on_ubuntu_22.sh → .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
 

.devcontainer/setup_documentation_environment_on_ubuntu_22.sh

@@ -0,0 +1,8 @@
+#!/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 makefile2graph
+python3 -m pip install -r requirements.txt

.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 

.github/workflows/ubuntu_2204_documentation_pipeline.yml

@@ -8,9 +8,9 @@ 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
-        run: cd build && make documentation
+        run: ./scripts/document.sh
 

.gitignore

@@ -1,3 +1,4 @@
 build/*
+output/*
 documentation/*.bbl 
 documentation/*.blg

cmake_modules/CreateLatexDocument.cmake

@@ -0,0 +1,43 @@
+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 ${_texsrc})
+
+  ADD_CUSTOM_COMMAND (
+    OUTPUT ${_output_folder}/${_name}.pdf
+    DEPENDS ${_texsrc} ${_resources} ${_bibliography}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMENT "Generating ${_name}"
+    VERBATIM
+    COMMAND ${PDFLATEX} -output-directory ${_output_folder}
+            ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex
+    COMMAND ${BIBER} --input-directory ${_output_folder} --output-directory
+            ${_output_folder} ${_name}.bcf
+    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}
+            ${CMAKE_CURRENT_SOURCE_DIR}/${_name}.tex)
+
+ENDMACRO ()

documentation/CMakeLists.txt

@@ -1,16 +1,28 @@
-INCLUDE (CreateLatexDocumentation)
+INCLUDE (CreateLatexDocument)
 
-SET (requirements_documents "requirements_document")
-SET (SOFTWARE_INTERN_MAIN_TEX ${requirements_documents}.tex)
-SET (SOFTWARE_INTERN_RESOURCES_FILES
+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 (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}")
+CREATELATEXDOCUMENT (
+  "${requirements_document}" "${REQUIREMENTS_DOCUMENT_MAIN_TEX}"
+  "${REQUIREMENTS_DOCUMENTS_RESOURCES_FILES}"
+  "${REQUIREMENTS_DOCUMENTS_BIBLIOGRAPHY}")
 
+# Doxygen documentation
+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_BINARY_DIR}/code_documentation.doxygen
+  VERBATIM
+  COMMAND doxygen ${CMAKE_CURRENT_BINARY_DIR}/code_documentation.doxygen
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  COMMENT "Building code documentation")
 ADD_CUSTOM_TARGET (
-  documentation
-  DEPENDS ${requirements_documents}
-  COMMENT "Building requirements documentation")
+  code_documentation
+  SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/code_documentation.doxygen.in
+  DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/code_documentation/html/index.html)

documentation/code_documentation.doxygen.in

@@ -0,0 +1,40 @@
+# Doxyfile
+
+# Set the project name
+PROJECT_NAME = ProjectName
+
+PROJECT_LOGO = @CMAKE_SOURCE_DIRECTORY@/documentation/resources/project_or_company_logo.png
+
+# Set the project version
+<!-- PROJECT_VERSION = 1.0 -->
+
+# Set the output directory for the generated documentation
+OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/code_documentation/
+CREATE_SUBDIRS = YES
+
+# Set the input directories for the source code
+INPUT = @CMAKE_SOURCE_DIR@/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
+<!-- GENERATE_HTML_HELP = YES -->
+
+# Enable the generation of a search index
+<!-- GENERATE_SEARCHHELP = YES -->
+
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES 
+GENERATE_DEPRECATEDLIST = YES
+
+
+
+GENERATE_LATEX = YES

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
@@ -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}

project/probelibrary/benchmark/probe_benchmark.cpp

@@ -1,3 +1,6 @@
+/*! \file probe_benchmark.cpp
+ * \brief Benchmark runtime of probe library
+ */
 #include <probe.h>
 
 #include <chrono>

project/probelibrary/include/probe.h

@@ -1,3 +1,9 @@
+/*! \file probe.h
+\brief Example library with a single free function (probe)
+*/
 #include <iostream>
 
+/*! \fn void Probe
+ * \brief Probe function
+ */
 void Probe();

project/probelibrary/tests/unit_test.cpp

@@ -1,6 +1,13 @@
+/*! \file unit_test.cpp
+\brief unit tests of probe library
+*/
+
 #include <gtest/gtest.h>
 #include <probe.h>
 
+/*! \test ProbeSanity
+ * \brief Check that the Probe function does not throw
+ */
 TEST(ProbeSanity, NoThrow) {
   EXPECT_NO_THROW(Probe());
 }

scripts/document.sh

@@ -0,0 +1,6 @@
+#!/bin/bash 
+set -euxo pipefail
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$DIR"/../build || exit 1
+make requirements_document 
+make code_documentation