Merge branch 'cargo_doc' into 'latest'

## Objective

Build a package's documentation for local package and all dependencies. Check the doc here 👉 [cargo-doc](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) for more information.

## How to use it

1. Ensure that your project has `Cargo.toml` file and its members folders are hierarchically below the workspace root.

1. Add this job URL inside the `include` list of your `.gitlab-ci.yml` file (see the [quick setup](/use-the-hub/#quick-setup)). You can specify [a fixed version](#changelog) instead of `latest`.

    ```yaml

      - remote: 'https://jobs.r2devops.io/latest/cargo_doc.yml'

    ```

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

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

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

## Job details

* Job name: `cargo_doc`

* Docker image:

[`rust:1.57-buster`](https://hub.docker.com/r/_/rust)

* Default stage: `build`

* When: `always`

### Variables

| Name | Description | Default |

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

| ONLY_LIB | Generate documentation of current library only | `false` | 

| PROJECT_ROOT | Relative to root of your repository, it is the path to your rust project | `.` | 

| RELEASE_MODE | Generate documentation with optimization for release. See the release profile here [release profile](https://doc.rust-lang.org/cargo/reference/profiles.html#release) | `true` | 

| OUTPUT_FOLDER | Directory where are output files | `website_build` | 

| ADDITIONAL_OPTIONS | Possibility to add more options into the command | ` ` | 

cargo_doc:

    image: rust:1.57-buster

    stage: build

    variables:

      ONLY_LIB: 'false'

      PROJECT_ROOT: '.'

      RELEASE_MODE: 'true'

      OUTPUT_FOLDER: "website_build"

      ADDITIONAL_OPTIONS: ''

    script:

      - cd $PROJECT_ROOT

      - if [ ! -f "Cargo.toml" ]; then

      -   echo "ERROR --> Any Cargo.toml file isn't present in the given folder $PROJECT_ROOT"

      -   exit 1

      - fi

      - if [ ${ONLY_LIB} == "true" ]; then

      -   ADDITIONAL_OPTIONS+=" --lib"

      - fi

      - if [ ${RELEASE_MODE} == "true" ]; then

      -   ADDITIONAL_OPTIONS+=" --release"

      - fi

      - if [ ! ${CI_PROJECT_DIR} -ef ${PROJECT_ROOT} ]; then

      -   OUTPUT_FOLDER="${CI_PROJECT_DIR}/${OUTPUT_FOLDER}"

      - fi

      - cargo doc --target-dir ${OUTPUT_FOLDER} $ADDITIONAL_OPTIONS

    artifacts:

      when: always

      expose_as: "Cargo_doc build"

      paths:

        - $OUTPUT_FOLDER

 No newline at end of file

name: cargo_doc

description: Cargo_doc aims to generate rustdoc for your project

default_stage: build

icon: 🧠

maintainer: DjNaGuRo

license: MIT

images:

  rust:1.57-buster

tools:

 No newline at end of file

* Initial version

 No newline at end of file