Commit 3049a2a7 authored by Ronny Moreas's avatar Ronny Moreas Committed by Pierre Smeyers
Browse files

feat: initial template version 



Signed-off-by: default avatarRonny Moreas <ronny.moreas@kuleuven.be>
parent 1e680acb

.releaserc.yml

+2 −2
Original line number Diff line number Diff line
@@ -18,5 +18,5 @@ plugins: [ 
  ]

]

branches:

  - "master"

  - "main"

tagFormat: "${version}"

README.md

+40 −74
Original line number Diff line number Diff line
@@ -18,94 +18,60 @@ include: 
The Sphinx template uses some global configuration used throughout all jobs.



| Name                     | Description                            | Default value     |

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

| `SPHINX_IMAGE` | The Docker image used to run `sphinx` | `registry.hub.docker.com/sphinx:latest` |

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

| `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` |

| `PIP_INDEX_URL`          | Python repository url | _none_ |

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



## Jobs



### `sphinx-build` job



This job performs **build and tests** at once.



It uses the following variable:

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



| Name                    | Description                                       | Default value     |

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

| `SPHINX_BUILD_ARGS`      | Arguments used by the build job          | `build --with-default-args` |



### SonarQube analysis



If you're using the SonarQube template to analyse your SPHINX code, here are 2 sample `sonar-project.properties` files.



```properties

# see: https://docs.sonarqube.org/latest/analysis/languages/sphinx/

# set your source directory(ies) here (relative to the sonar-project.properties file)

sonar.sources=.

# exclude unwanted directories and files from being analysed

sonar.exclusions=output/**,**/*_test.sphinx



# set your tests directory(ies) here (relative to the sonar-project.properties file)

sonar.tests=.

sonar.test.inclusions=**/*_test.sphinx

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

| `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` |



# tests report (TODO)

sonar.sphinx.testExecutionReportPaths=reports/sonar_test_report.xml

# coverage report (TODO)

sonar.sphinx.coverage.reportPaths=reports/coverage.cov

```



More info:



* [Sphinx language support](https://docs.sonarqube.org/latest/analysis/languages/sphinx/)

* [test coverage & execution parameters](https://docs.sonarqube.org/latest/analysis/coverage/)

* [third-party issues](https://docs.sonarqube.org/latest/analysis/external-issues/)



### `sphinx-lint` job

### `sphinx-lychee` job



This job performs a [lint](link-to-the-tool) analysis of your code, mapped to the `build` stage.



It uses the following variables:

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



| Name                    | Description                                       | Default value     |

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

| `SPHINX_LINT_IMAGE`      | The Docker image used to run the lint tool | `sphinx-lint:latest` |

| `SPHINX_LINT_DISABLED`   | Set to `true` to disable the `lint` analysis| _none_ (enabled) |

| `SPHINX_LINT_ARGS`       | Lint [options and arguments](link-to-the-cli-options) | `--serevity=medium` |

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

| `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` |



### `sphinx-depcheck` job

## Publishing



This job enables a manual [dependency check](link-to-the-tool) analysis of your code, mapped to the `test` stage.

:warning: this template is not a deployment template and it only builds a Sphinx project.



It uses the following variables:

You might deploy the generated site using a [GitLab pages](https://docs.gitlab.com/ee/user/project/pages/) job (there is [a variant for that](#gitlab-pages-variant)) or any other method you see fit.



| Name                  | Description                                | Default value     |

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

| `SPHINX_DEPCHECK_IMAGE`  | The Docker image used to run the dependency check tool | `sphinx-depcheck:latest` |

| `SPHINX_DEPCHECK_ARGS`   | Dependency check [options and arguments](link-to-the-cli-options) | _none_ |

## Variants



### `sphinx-publish` job

### GitLab Pages variant



This job is **disabled by default** and performs a publish of your built binaries.

Basically it copies the content of the sphinx generated site folder (`site` by default) to the `public` folder which is published by [GitLab pages](https://docs.gitlab.com/ee/user/project/pages/#how-it-works).



It uses the following variables:

If you wish to use it, add the following to your `gitlab-ci.yml`:



| Name                  | Description                            | Default value     |

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

| `SPHINX_PUBLISH_ENABLED` | Variable to enable the publish job     | _none_ (disabled) |

| `SPHINX_PUBLISH_ARGS`    | Arguments used by the publish job      | `publish --with-default-args` |

| :lock: `SPHINX_PUBLISH_LOGIN` | Login to use to publish           | **has to be defined** |

| :lock: `SPHINX_PUBLISH_PASSWORD` | Password to use to publish     | **has to be defined** |



### Secrets management



Here are some advices about your **secrets** (variables marked with a :lock:):



1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-custom-variable) to prevent them from being inadvertently

      displayed in your job logs,

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-custom-variable) if you want to secure some secrets

      you don't want everyone in the project to have access to (for instance production secrets).

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#masked-variable-requirements), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`:

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (ex: `$` -> `$$`).
 
```yaml

include:

  # main template

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

    ref: '1.0.0'

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

  # GitLab pages variant

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

    ref: '1.0.0'

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

```

Sphinx.r2.yml

+2 −1
Original line number Diff line number Diff line
@@ -3,10 +3,11 @@ files: 
    documentation: ./README.md

    changelog: ./CHANGELOG.md

data:

    description: "Create intelligent and beautiful documentation with Sphinx"

    description: "Build your documentation with Sphinx"

    labels:

    - to be continuous

    - Documentation

    - Build

    - Sphinx

    public: true

    license: LGPL v3

kicker.json

+66 −56
Original line number Diff line number Diff line 


{

  "name": "Sphinx",

  "description": "Build, test and verify your [Sphinx](https://www.sphinx-doc.org) projects",

  "description": "Build your documentation with [Sphinx](https://www.sphinx-doc.org/)",

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

  "kind": "build",

  "variables": [

    {

      "name": "SPHINX_IMAGE",

      "description": "The Docker image used to run `sphinx`",

      "default": "registry.hub.docker.com/sphinx:1.2.3"

      "description": "The Docker image used to run Sphinx",

      "default": "ghcr.io/sphinx-doc/sphinx:latest"

    },

    {

      "name": "SPHINX_BUILD_ARGS",

      "description": "Arguments used by the build job",

      "default": "build --with-default-args",

      "description": "[`sphinx-build` options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html)) to be used",

      "default": "-M html"

    },

    {

      "name": "SPHINX_PROJECT_DIR",

      "description": "Sphinx project root directory",

      "default": "."

    },

    {

      "name": "SPHINX_SOURCE_DIR",

      "description": "Sphinx source directory (relative to `$SPHINX_PROJECT_DIR`) containing the Sphinx `conf.py` file",

      "default": "source",

      "advanced": true

    }

  ],

  "features": [

    },

    {

      "id": "lint",

      "name": "SPHINX lint",

      "description": "[SPHINX lint](link-to-the-tool) analysis",

      "disable_with": "SPHINX_LINT_DISABLED",

      "variables": [

      "name": "SPHINX_BUILD_DIR",

      "description": "Sphinx build output directory (relative to `$SPHINX_PROJECT_DIR`)",

      "default": "build",

      "advanced": true

    },    

    {

          "name": "SPHINX_LINT_IMAGE",

          "description": "The Docker image used to run the lint tool",

          "default": "registry.hub.docker.com/sphinx-lint:latest"

      "name": "SPHINX_REQUIREMENTS_FILE",

      "description": "Requirements file (relative to `$SPHINX_PROJECT_DIR`). If the file is not found in the repository, requirements are read from the `SPHINX_REQUIREMENTS` variable",

      "default": "requirements.txt",

      "advanced": true

    },

    {

          "name": "SPHINX_LINT_ARGS",

          "description": "Lint [options and arguments](link-to-the-cli-options)",

          "default": "--serevity=medium",

      "name": "SPHINX_REQUIREMENTS",

      "description": "Space separated requirements (ignored if a requirement file is found)",

      "default": "",

      "advanced": true

        }

      ]

    },

    {

      "id": "depcheck",

      "name": "SPHINX dependency check",

      "description": "[SPHINX dependency check](link-to-the-tool) analysis",

      "variables": [

      "name": "SPHINX_PREBUILD_SCRIPT",

      "description": "Pre-build hook script (relative to `$SPHINX_PROJECT_DIR`)",

      "default": "sphinx-pre-build.sh",

      "advanced": true

    },

    {

          "name": "SPHINX_DEPCHECK_IMAGE",

          "description": "The Docker image used to run the dependency check tool",

          "default": "registry.hub.docker.com/sphinx-depcheck:latest"

      "name": "PIP_INDEX_URL",

      "description": "Python repository url",

      "advanced": true

    },

    {

          "name": "SPHINX_DEPCHECK_ARGS",

          "description": "Dependency check [options and arguments](link-to-the-cli-options)",

      "name": "PIP_OPTS",

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

      "advanced": true

    }

      ]

    },

  ],

  "features": [

    {

      "id": "publish",

      "name": "Publish",

      "description": "Publish your package to a repository",

      "enable_with": "SPHINX_PUBLISH_ENABLED",

      "id": "lychee",

      "name": "lychee",

      "description": "Checks broken links and emails with [lychee](https://github.com/lycheeverse/lychee)",

      "enable_with": "SPHINX_LYCHEE_ENABLED",

      "variables": [

        {

          "name": "SPHINX_PUBLISH_ARGS",

          "description": "Arguments used by the publish job",

          "default": "publish --with-default-args",

          "name": "SPHINX_LYCHEE_IMAGE",

          "description": "The Docker image used to run [lychee](https://github.com/lycheeverse/lychee)",

          "default": "registry.hub.docker.com/lycheeverse/lychee:latest",

          "advanced": true

        },

        {

          "name": "SPHINX_PUBLISH_LOGIN",

          "description": "Login to use to publish",

          "secret": true

        },

        {

          "name": "SPHINX_PUBLISH_PASSWORD",

          "description": "Password to use to publish",

          "secret": true

          "name": "SPHINX_LYCHEE_ARGS",

          "description": "[lychee arguments](https://github.com/lycheeverse/lychee#commandline-parameters) to execute",

          "default": "--exclude-loopback $SPHINX_SOURCE_DIR/**/*.rst"

        }

      ]

    }

  ],

  "variants": [

    {

      "id": "pages",

      "name": "GitLab Pages",

      "description": "Adds a job to publish the generated documentation to GitLab pages",

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

    }

  ]

}

logo.png

−60.4 KiB (8.84 KiB)
Loading image diff...