Merge branch '111-add-doxygen-job' into 'latest'

# 📃 Doxygen

## Description

This job generates documentation from popular programming languages

in different output format using this tool [Doxygen](https://www.doxygen.nl/)

Programming languages supported by Doxygen include C, C++, C#, D, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, and VHDL.

Other languages can be supported with additional code.

## How to use it

1. Ensure that your source code is documenting using [Doxygen syntax](https://www.doxygen.nl/manual/docblocks.html)

2. Add the corresponding URL to your `.gitlab-ci.yml` file (see [Getting

   started](/getting-started)). Example:

    ```yaml

    include:

      - remote: 'https://jobs.go2scale.io/doxygen.yml'

    ```

3. If you need to customize the job (stage, variables, ...) 👉 check the [jobs

   customization](/use-the-hub/#jobs-customization)

4. Well done, your job is ready to work ! 😀

## Job details

* Job name: `doxygen`

* Docker image: [`alpine:3.12.1`](https://hub.docker.com/_/alpine)

* Default stage: `build`

* When: `always`

### Variables

| Name | Description | Default |

| ---- | ----------- | ------- |

| `INPUT` <img width=650px>               | Input directory of your source files <img width=125>| `.` <img width=300>|

| `DOXYGEN_CONFIGFILE`               | Name of your Doxygen configuration file| `Doxyfile`|

| `DOXYGEN_PROJECT_NAME`               | Name of your Doxygen project, for the documentation title| `$CI_PROJECT_NAME`  (Gitlab project name) |

| `DOXYGEN_INPUT`               | The path to your documented source files| `.`|

| `DOXYGEN_OUTPUT_DIRECTORY`               | The path of your documentation generated| `.`|

| `DOXYGEN_OUTPUT_LANGUAGE`               | The language in which your documentation is written| `English`|

| `DOXYGEN_GENERATE_LATEX`               | Set to YES if you want to generate LaTeX documentation | `YES`|

| `DOXYGEN_LATEX_OUTPUT`               | The path of your LaTeX documentation generated| `latex/`|

| `DOXYGEN_GENERATE_HTML`               | Set to YES if you want to generate HTML documentation | `YES`|

| `DOXYGEN_HTML_OUTPUT`               | The path of your LaTeX documentation generated| `documentation_build/`|

| `DOXYGEN_HTML_EXTRA_STYLESHEET`               | The path of additional user-defined cascading style sheets [CSS](https://www.w3schools.com/css/)| ` `|

| `DOXYGEN_RECURSIVE`               | Specify whether or not subdirectories should be searched for input files as well| `NO`|

| `DOXYGEN_EXCLUDE`               | Specify files and/or directories that should be excluded from the INPUT source files| ` `|

| `DOXYGEN_EXCLUDE_PATTERNS`               | If the value of the INPUT tag contains directories, you can use the EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude certain files from those directories.| ` `|

| `DOXYGEN_PROJECT_LOGO`               | The path of the logo (max-height:55px, max-width:200px) to include in your documentation generated| ` `|

!!! note

    All paths defined in variables are starting from the root of your repository.

### Artifacts

Result of documentation build is [exposed

as](https://docs.gitlab.com/ee/ci/yaml/#artifactsexpose_as) `Doyxgen build` in

merge requests.

!!! warning

    Exposition of artifact doesn't work currently because of [this issue from

    Gitlab](https://gitlab.com/gitlab-org/gitlab/-/issues/37129). As soon as

    the issue will be fixed, exposed artifacts will be available in merge

    requests.

stages:

  - build

doxygen:

    image: alpine:3.12.1

    stage: build

    variables:

      ## JOB variables ##

      JOB_DOXYGEN_VERSION: "1.8.18-r0"

      ## DOXYGEN variables ##

      # All variables supported by Doxygen are listed here:https://www.doxygen.nl/manual/config.html

      DOXYGEN_CONFIGFILE: "Doxyfile"

      # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard)

      # that should identify the project for which the documentation is generated.

      # This name is used in the title of most generated pages and in a few other places.

      # The default value is: "". Inside the script section if this value is "" it will be replaced by your project name

      DOXYGEN_PROJECT_NAME: ""

      # The INPUT tag is used to specify the files and/or directories that contain documented source files.

      # You may enter file names like myfile.cpp or directories like /usr/src/myproject. Separate the files or directories with spaces.

      DOXYGEN_INPUT: "src/"

      # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path into which the generated documentation will be written.

      # If a relative path is entered, it will be relative to the location where doxygen was started.

      # If left blank the current directory will be used.

      DOXYGEN_OUTPUT_DIRECTORY: "./"

      # The OUTPUT_LANGUAGE tag is used to specify the language in which all documentation generated by doxygen is written. Doxygen will use this information to generate all constant output in the proper language.

      # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, Ukrainian and Vietnamese.

      # The default value is: English.

      DOXYGEN_OUTPUT_LANGUAGE: "English"

      # If the GENERATE_LATEX tag is set to YES, doxygen will generate $\mbox{\LaTeX}$ output.

      # The default value is: YES.

      DOXYGEN_GENERATE_LATEX: "YES"

      # The LATEX_OUTPUT tag is used to specify where the $\mbox{\LaTeX}$ docs will be put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put in front of it.

      # The default directory is: latex.

      # This tag requires that the tag GENERATE_LATEX is set to YES.

      DOXYGEN_LATEX_OUTPUT: "latex/"

      # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output

      # The default value is: YES.

      DOXYGEN_GENERATE_HTML: "YES"

      # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put in front of it.

      # The default directory is: html.

      # This tag requires that the tag GENERATE_HTML is set to YES.

      DOXYGEN_HTML_OUTPUT: "documentation_build/"

      # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined cascading style sheets that are included after the standard style sheets created by doxygen.

      # Using this option one can overrule certain style aspects. This is preferred over using HTML_STYLESHEET since it does not replace the standard style sheet and is therefore more robust against future updates.

      # Doxygen will copy the style sheet files to the output directory.

      DOXYGEN_HTML_EXTRA_STYLESHEET: ""

      # The RECURSIVE tag can be used to specify whether or not subdirectories should be searched for input files as well.

      DOXYGEN_RECURSIVE: "NO"

      # 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 subdirectory from a directory tree whose root is specified with the INPUT tag.

      # Note that relative paths are relative to the directory from which doxygen is run.

      DOXYGEN_EXCLUDE: ""

      # If the value of the INPUT tag contains directories, you can use the EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude certain files from those directories.

      # Note that the wildcards are matched against the file with absolute path, so to exclude all test directories for example use the pattern */test/*

      DOXYGEN_EXCLUDE_PATTERNS: ""

      # With the PROJECT_LOGO tag one can specify a logo or an icon that is included in the documentation.

      # The maximum height of the logo should not exceed 55 pixels and the maximum width should not exceed 200 pixels.

      # Doxygen will copy the logo to the output directory.

      DOXYGEN_PROJECT_LOGO: ""

    script:

       # Initiate the project name value.

       - if [ -z ${DOXYGEN_PROJECT_NAME} ]; then

       -     export DOXYGEN_PROJECT_NAME="${CI_PROJECT_NAME}"

       - fi

       # Install doxygen

       - apk add --no-cache doxygen==${JOB_DOXYGEN_VERSION}

       # Include config Doxyfile and override default variables

       - if [ ! -f "$DOXYGEN_CONFIGFILE" ]; then

       -   touch ${DOXYGEN_CONFIGFILE}

       -   echo "PROJECT_NAME=${DOXYGEN_PROJECT_NAME}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "INPUT=${DOXYGEN_INPUT}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "OUTPUT_DIRECTORY=${DOXYGEN_OUTPUT_DIRECTORY}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "OUTPUT_LANGUAGE=${DOXYGEN_OUTPUT_LANGUAGE}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "GENERATE_LATEX=${DOXYGEN_GENERATE_LATEX}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "LATEX_OUTPUT=${DOXYGEN_LATEX_OUTPUT}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "GENERATE_HTML=${DOXYGEN_GENERATE_HTML}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "HTML_OUTPUT=${DOXYGEN_HTML_OUTPUT}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "HTML_EXTRA_STYLESHEET=${DOXYGEN_HTML_EXTRA_STYLESHEET}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "RECURSIVE=${DOXYGEN_RECURSIVE}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "EXCLUDE=${DOXYGEN_EXCLUDE}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "EXCLUDE_PATTERNS=${DOXYGEN_EXCLUDE_PATTERNS}" >> ${DOXYGEN_CONFIGFILE}

       -   echo "PROJECT_LOGO=${DOXYGEN_PROJECT_LOGO}" >> ${DOXYGEN_CONFIGFILE}

       - fi

       - doxygen ${DOXYGEN_CONFIGFILE}

    artifacts:

       when: on_success

       expose_as: "Doyxgen build"

       paths:

         - "$DOXYGEN_HTML_OUTPUT"

         - "$DOXYGEN_LATEX_OUTPUT"

name: doxygen

description: A ready to use doxygen job to build your documentation

default_stage: build

icon: 📃 

maintainer: coconux

license: MIT

/** @file sample.cpp

@author Lastname:Firstname:A00123456:cscxxxxx

@version Revision 1.1

@brief Illustrates doxygen-style comments for documenting a C++

program file and the functions in that file.

@details If you want to add any further detailed description of

what is in the file, then place it here (after the first statement)

and it will appear in the detailed description section of the HTML

output description for the file.

@date Monday, September 19, 2011

*/

/**

@mainpage

This short program contains some sample code illustrating 

how the doxygen comments must appear

- for documenting a file, and in particular

- for documenting functions

.

when we intend to use the doxygen tool for preparing HTML

documentation of our code. Note that this file is intended

<em>only</em> to illustrate a particular set of <b>commenting

conventions</b> and how they show up when implemented with

doxygen. Your actual requirements may not be the same as

shown here. Im particular you may need less (or more) than

is shown here.

Pay careful attention, in the source code,\n to the distinction

between the special doxygen comments,<br>which produce output

here, and regular C++ comments which are ignored by doxygen,

and look at the source code to see how line breaks in this

paragraph are produced.

*/

/*

Author self-assessment statement:

This program is complete and working according to spcecifications,

according to the best of my knowledge.

Or ...

This program is incomplete in the following ways

1. ...

2. ...

And/or ...

This program still contains the following bugs:

1. ...

2. ...

And by the way, note that this is a C++ but non-doxygen comment,

so it will not appear in the HTML displays produced by doxygen.

*/

//Include section

#include <iostream>

#include <string>

using namespace std;

//Prototype section

void DoSomething

    (

    int numberOfPositions,   //in

    char& firstInitial,      //inout

    string& stringOfInitials //out

    );

/**<

A single statement goes here to give a high-level description of

the function, which is ended by the first period. Any further

description of the function, such as this statement that comes

after the first statement, will appear as part of the "detailed

description" for this function. The brief description may also

be repeated here immediately prior to the detailed description,

but the configuration file for this example is currently set to

disable that feature.

@return void

@param numberOfPositions The number of positions firstInitial is to

be  moved forward.

@param firstInitial A character representing the first letter in a

person's first name (for example).

@param stringOfInitials A string in which all characters are the

same.

@pre

-# numberOfPositions contains a positive integer.

-# firstInitial contains a printable character at least numberOfPositions

positions from the end of the printable character set.

@post

-# firstInitial contains the character numberOfPositions to the right of

its original value.

-# stringOfInitials contains a string of length numberOfPositions

in which each character is the original value of firstInitial.

*/

int numberOfDigits

    (

    int n //in

    );

/**<

Compute and return the number of digits in a positive integer.

The style used for the pre/post coditions of this function is

purposely different from that for the void function given above,

just so you can see the differnce in the HTML output.

@return The number of digits in n.

@param n An integer, the number of whose digits is desired.

@pre n contains a positive integer.

This is some other precondition, and note that it does not

start on a new line.

@post

The number of digits in n has been returned.

\n This is some other post condition, and note that it does start

on a new line.

*/

/**

 * \fn int main (void)

 * \brief Entry point

 *

 * \return EXIT_SUCCESS - Regular exit of the program

 */n

int main()

{

    int count = 6;

    char myInitial = 'P';

    string allOneLetter;

    DoSomething(count, myInitial, allOneLetter);

    cout << endl;

    cout << count << " " << myInitial << " " << allOneLetter << endl;

    cout << "\nNumber of digits in 0 ...... " << numberOfDigits(0);

    cout << "\nNumber of digits in 7 ...... " << numberOfDigits(7);

    cout << "\nNumber of digits in 123 .... " << numberOfDigits(123);

    cout << "\nNumber of digits in 12345 .. " << numberOfDigits(12345);

    cout << endl << endl;

    cout << "\nPress Enter to continue ... ";  cin.ignore(80, '\n');

    return EXIT_SUCCESS;

}

//Function definition section

//Definitions must be in the same order as the prototypes.

void DoSomething

    (

    int numberOfPositions,   //in

    char& firstInitial,      //inout

    string& stringOfInitials //out

    )

{

    stringOfInitials = string(numberOfPositions, firstInitial);

    firstInitial = (char)(((int)firstInitial)+numberOfPositions);

}

int numberOfDigits

    (

    int n //in

    )

{

    int count = 0;

    do

    {

        n /= 10;

        ++count;

    }

    while (n != 0);

    return count;

}

* Initial version