feat (job): sphinx_build

## Objective

[Sphinx](https://www.sphinx-doc.org/en/master/index.html){:target="_blank"} is a tool that makes it easy to create intelligent and beautiful documentation for python projects.

## How to use it

1. Ensure that your project has been initialized with the `sphinx-quickstart` command, it will generate the source directory where you can edit your `conf.py` file.

1. You can specify the `APIDOC_SOURCE` variable, in this case the job will run the `sphinx-apidoc` command which will generate the Sphinx sources automatically. If you leave it empty the `sphinx-apidoc` command will be skipped.

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/sphinx_build.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: `sphinx_build`

* Docker image:

[`python:3.10-buster`](https://hub.docker.com/r/_/python){:target="_blank"}

* Default stage: `build`

* When: only run on `main` branch

### Variables

| Name | Description | Default |

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

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

| `SPHINX_THEME` | HTML theme builder to download, sphinx comes with [builtin themes](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes){:target="_blank"}. Check this [site](https://sphinx-themes.org/){:target="_blank"} to download third party themes | ` ` |

| `SPHINX_BUILDER` | Builder used for site generation, check the [builder list](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#options){:target="_blank"}.| `html` |

| `SPHINX_SOURCE` | Directory name of the source files to build the Sphinx website.  | `docs/` |

| `SPHINX_OUTPUT` | Output directory path produced by the `sphinx-build`. | `website_build/` |

| `SPHINX_OPTIONS` | Possibility to add more [options](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#options){:target="_blank"} into the `sphinx-build` command. | ` ` |

| `APIDOC_SOURCE` | Directory name of the source files to build the Sphinx sources automatically, check the `sphinx-apidoc` [documentation](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html){:target="_blank"} to learn more. Leave this variable empty if you don't want to execute this command. | ` ` |

| `APIDOC_OUTPUT` | Output directory path produced by the `sphinx-apidoc`. | `docs/reference/source/` |

| `APIDOC_OPTIONS` | Possibility to add more [options](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#options){:target="_blank"} into the `sphinx-apidoc` command. | ` ` |

name: sphinx_build

description: Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for python projects.

default_stage: build

icon: 📃

maintainer: valentin.guyon.vg

license: Apache-2.0

images:

  "python": "3.10-buster"

tools:

labels:

  - GitLab

  - Documentation

  - Build

# Job from R2Devops hub --> r2devops.io

stages:

  - build

sphinx_build:

  image:

    name: python:3.10-buster

    entrypoint: [""]

  stage: build

  variables:

    PROJECT_ROOT: "."

    SPHINX_THEME: ""

    SPHINX_BUILDER: "html"

    SPHINX_SOURCE: "docs/"

    SPHINX_OUTPUT: "website_build/"

    SPHINX_OPTIONS: ""

    APIDOC_SOURCE: ""

    APIDOC_OUTPUT: "docs/reference/source/"

    APIDOC_OPTIONS: ""

  script:

    - cd ${PROJECT_ROOT}

    - pip install Sphinx ${SPHINX_THEME} .

    - if [[ ${APIDOC_SOURCE} != "" ]]; then

    -   sphinx-apidoc ${APIDOC_OPTIONS} -o ${APIDOC_OUTPUT} ${APIDOC_SOURCE}

    - fi

    - sphinx-build -b ${SPHINX_BUILDER} ${SPHINX_SOURCE} ${SPHINX_OUTPUT} ${SPHINX_OPTIONS}

  artifacts:

    paths:

      - ${SPHINX_OUTPUT}

  rules:

    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

* Initial version

 No newline at end of file