gitlab-templates/RTD.gitlab-ci.yml

   1 # ReadTheDocs Workflow
   2 #
   3 # This workflow adds these builds to projects:
   4 #
   5 #   docs-build:
   6 #       Generate a html sphinx-build from the $DOCS_DIRECTORY
   7 #
   8 #   docs-link-check:
   9 #       Run a non-blocking sphinx-build linkcheck against
  10 #       the $DOCS_DIRECTORY
  11 #
  12 #   pages:
  13 #       Serve the built documentation as the Gitlab Pages site for
  14 #       the project
  15 #
  16 # Both docs-build and docs-link-check run on merge requests and merges
  17 # to the default branch that modify files under the $DOCS_DIRECTORY,
  18 # while pages only run on merges.
  19 #
  20 # Scheduled builds can be enabled when creating a schedule job and
  21 # specifying DOCS_SCHEDULE = "true" in build variables
  22 ---
  23 variables:
  24   PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
  25   DOCS_DIRECTORY: "docs"
  26
  27 .docs-cache: &docs-cache
  28   paths:
  29     - .cache/pip
  30     - venv/
  31
  32 .docs-before-script: &docs-before-script
  33   - python -V
  34   - pip install virtualenv
  35   - virtualenv venv
  36   - source venv/bin/activate
  37   - pip install Sphinx
  38   - |
  39     if [ -f "$DOCS_DIRECTORY/requirements.txt" ]; then
  40       pip install -r "$DOCS_DIRECTORY/requirements.txt"
  41     fi
  42
  43 docs-build:
  44   stage: build
  45   image: python:3
  46   before_script:
  47     - *docs-before-script
  48   script: |
  49      sphinx-build -T -b html -D language=en $DOCS_DIRECTORY _build/html
  50   cache: *docs-cache
  51   artifacts:
  52     paths:
  53       - _build/html
  54   rules:
  55     - if: $CI_PIPELINE_SOURCE == "schedule" && $DOCS_SCHEDULE != "true"
  56       when: never
  57     - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  58       changes:
  59         - $DOCS_DIRECTORY/*
  60
  61 docs-link-check:
  62   stage: test
  63   allow_failure: true
  64   needs: []
  65   image: python:3
  66   before_script:
  67     - *docs-before-script
  68   script: |
  69       sphinx-build -T -b linkcheck $DOCS_DIRECTORY _build/linkcheck
  70   cache: *docs-cache
  71   artifacts:
  72     paths:
  73       - _build/linkcheck
  74   rules:
  75     - if: $CI_PIPELINE_SOURCE == "schedule" && $DOCS_SCHEDULE != "true"
  76       when: never
  77     - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  78       changes:
  79         - $DOCS_DIRECTORY/*
  80
  81 pages:
  82   stage: deploy
  83   image: python:3
  84   script: |
  85       mkdir public
  86       mv _build/html/* public/
  87   artifacts:
  88     paths:
  89       - public
  90   rules:
  91     - if: $CI_PIPELINE_SOURCE == "schedule"
  92       when: never
  93     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  94       changes:
  95         - $DOCS_DIRECTORY/*