Commit 44318dff authored by girija.saintange's avatar girija.saintange Committed by Pierre Smeyers
Browse files

feat: migrate to CI/CD component 

⚠️ requires GitLab 16.6 or later
parent d4211a29

.gitlab-ci.yml

+1 −1
Original line number Diff line number Diff line
@@ -10,7 +10,7 @@ include: 
    file: '/templates/validation.yml'

  - project: 'to-be-continuous/bash'

    ref: '3.3'

    file: 'templates/gitlab-ci-bash.yml'

    file: '/templates/gitlab-ci-bash.yml'

  - project: 'to-be-continuous/semantic-release'

    ref: '3.7'

    file: '/templates/gitlab-ci-semrel.yml'

README.md

+41 −23
Original line number Diff line number Diff line
@@ -4,30 +4,52 @@ This project implements a GitLab CI/CD template to create intelligent and beauti 


## Usage



In order to include this template in your project, add the following to your `gitlab-ci.yml`:

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.



### Use as a CI/CD component



Add the following to your `gitlab-ci.yml`:



```yaml

include:

  # 1: include the component

  - component: gitlab.com/to-be-continuous/sphinx/gitlab-ci-sphinx@1.0.0

    # 2: set/override component inputs

    inputs:

      build-dir: website # ⚠ this is only an example

```



### Use as a CI/CD template (legacy)



Add the following to your `gitlab-ci.yml`:



```yaml

include:

  # 1: include the template

  - project: 'to-be-continuous/sphinx'

    ref: '1.0.0'

    file: '/templates/gitlab-ci-sphinx.yml'



variables:

  # 2: set/override template variables

  SPHINX_BUILD_DIR: website # ⚠ this is only an example

```



## Global configuration



The Sphinx template uses some global configuration used throughout all jobs.



| Name                     | Description                            | Default value     |

| Input / Variable | Description                            | Default value     |

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

| `SPHINX_IMAGE`           | The Docker image used to run Sphinx    | `ghcr.io/sphinx-doc/sphinx:latest` |

| `SPHINX_PROJECT_DIR`     | Sphinx project root directory | `.` |

| `SPHINX_SOURCE_DIR`      | Sphinx source directory (relative to `$SPHINX_PROJECT_DIR`) containing the Sphinx `conf.py` file | `source` |

| `SPHINX_BUILD_DIR`       | Sphinx build directory (relative to `$SPHINX_PROJECT_DIR`), the path will be declared as artifact | `build` |

| `SPHINX_REQUIREMENTS_FILE` | Requirements file. If the file is not found in the repository, requirements are read from the `SPHINX_REQUIREMENTS` variable | `requirements.txt` |

| `SPHINX_REQUIREMENTS`    | Space separated requirements (ignored if a requirement file is found) | _none_ |

| `SPHINX_PREBUILD_SCRIPT` | Pre-build hook script | `sphinx-pre-build.sh` |

| `image` / `SPHINX_IMAGE` | The Docker image used to run Sphinx    | `ghcr.io/sphinx-doc/sphinx:latest` |

| `project-dir` / `SPHINX_PROJECT_DIR` | Sphinx project root directory | `.` |

| `source-dir` / `SPHINX_SOURCE_DIR` | Sphinx source directory (relative to `$SPHINX_PROJECT_DIR`) containing the Sphinx `conf.py` file | `source` |

| `build-dir` / `SPHINX_BUILD_DIR` | Sphinx build directory (relative to `$SPHINX_PROJECT_DIR`), the path will be declared as artifact | `build` |

| `requirements-file` / `SPHINX_REQUIREMENTS_FILE` | Requirements file. If the file is not found in the repository, requirements are read from the `SPHINX_REQUIREMENTS` variable | `requirements.txt` |

| `requirements` / `SPHINX_REQUIREMENTS` | Space separated requirements (ignored if a requirement file is found) | _none_ |

| `prebuild-script` / `SPHINX_PREBUILD_SCRIPT` | Pre-build hook script | `sphinx-pre-build.sh` |

| `PIP_INDEX_URL` | Python repository url | _none_ |

| `PIP_OPTS`               | pip extra [options](https://pip.pypa.io/en/stable/cli/pip/#general-options) | _none_ |

| `pip-opts` / `PIP_OPTS` | pip extra [options](https://pip.pypa.io/en/stable/cli/pip/#general-options) | _none_ |



## Jobs
@@ -35,20 +57,20 @@ The Sphinx template uses some global configuration used throughout all jobs. 


This job performs Sphinx **build**. It uses the following variable:



| Name                    | Description                                       | Default value     |

| Input / Variable | Description                                       | Default value     |

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

| `SPHINX_BUILD_ARGS`     | [`sphinx-build` options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html)) to be used in the build job, | `-M html` |

| `build-args` / `SPHINX_BUILD_ARGS` | [`sphinx-build` options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html)) to be used in the build job, | `-M html` |





### `sphinx-lychee` job



This job checks links with [lychee](https://github.com/lycheeverse/lychee). It uses the following variable:



| Name                    | Description                                       | Default value     |

| Input / Variable | Description                                       | Default value     |

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

| `SPHINX_LYCHEE_ENABLED`    | Set to `true` to enable this job                  | _none_ (disabled) |

| `SPHINX_LYCHEE_IMAGE`      | The Docker image used to run [lychee](https://github.com/lycheeverse/lychee) | `registry.hub.docker.com/lycheeverse/lychee:latest` |

| `SPHINX_LYCHEE_ARGS`       | [lychee arguments](https://github.com/lycheeverse/lychee#commandline-parameters) to execute | `--exclude-loopback $SPHINX_SOURCE_DIR/**/*.rst` |

| `lychee-enabled` / `SPHINX_LYCHEE_ENABLED` | Set to `true` to enable this job                  | _none_ (disabled) |

| `lychee-image` / `SPHINX_LYCHEE_IMAGE` | The Docker image used to run [lychee](https://github.com/lycheeverse/lychee) | `registry.hub.docker.com/lycheeverse/lychee:latest` |

| `lychee-args` / `SPHINX_LYCHEE_ARGS` | [lychee arguments](https://github.com/lycheeverse/lychee#commandline-parameters) to execute | `--exclude-loopback $SPHINX_SOURCE_DIR/**/*.rst` |



## Publishing
@@ -67,11 +89,7 @@ If you wish to use it, add the following to your `gitlab-ci.yml`: 
```yaml

include:

  # main template

  - project: 'to-be-continuous/sphinx'

    ref: '1.0.0'

    file: '/templates/gitlab-ci-sphinx.yml'

  - component: gitlab.com/to-be-continuous/sphinx/gitlab-ci-sphinx@1.0.0

  # GitLab pages variant

  - project: 'to-be-continuous/sphinx'

    ref: '1.0.0'

    file: '/templates/gitlab-ci-sphinx-pages.yml'

  - component: gitlab.com/to-be-continuous/sphinx/gitlab-ci-sphinx-pages@1.0.0

```

kicker.json

+2 −5
Original line number Diff line number Diff line
@@ -3,6 +3,8 @@ 
  "description": "Build your documentation with [Sphinx](https://www.sphinx-doc.org/)",

  "template_path": "templates/gitlab-ci-sphinx.yml",

  "kind": "build",

  "prefix": "sphinx",

  "is_component": true,

  "variables": [

    {

      "name": "SPHINX_IMAGE",
@@ -49,11 +51,6 @@ 
      "default": "sphinx-pre-build.sh",

      "advanced": true

    },

    {

      "name": "PIP_INDEX_URL",

      "description": "Python repository url",

      "advanced": true

    },

    {

      "name": "PIP_OPTS",

      "description": "pip extra [options](https://pip.pypa.io/en/stable/cli/pip/#general-options)",

logo.png

+5.69 KiB (14.5 KiB)
Loading image diff...

templates/gitlab-ci-sphinx-pages.yml

+5 −2
Original line number Diff line number Diff line 
# ==================================================

# Variables definition

# ==================================================

spec:

  inputs: {}

---

variables:

  # default production ref name (pattern)

  PROD_REF: '/^(master|main)$/'

  PROD_REF: /^(master|main)$/

  # default integration ref name (pattern)

  INTEG_REF: '/^develop$/'

  INTEG_REF: /^develop$/



# ==================================================

# Stages definition