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 # If extra dependencies are needed for builds they will be installed
  24 # from the $DOCS_REQUIREMENTS location.
  25 ---
  26 variables:
  27   PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
  28   DOCS_DIRECTORY: "docs"
  29   DOCS_REQUIREMENTS: "$DOCS_DIRECTORY/requirements.txt"
  30   STABLE_BRANCH: "stable/*"
  31
  32 .docs-cache: &docs-cache
  33   paths:
  34     - .cache/pip
  35     - venv/
  36
  37 .docs-before-script: &docs-before-script
  38   - python -V
  39   - pip install virtualenv
  40   - virtualenv venv
  41   - source venv/bin/activate
  42   - pip install Sphinx
  43   - |
  44     if [ -f "$DOCS_REQUIREMENTS" ]; then
  45       pip install -r "$DOCS_REQUIREMENTS"
  46     fi
  47
  48 docs-build:
  49   stage: build
  50   image: python:3
  51   before_script:
  52     - *docs-before-script
  53   script: |
  54      sphinx-build -T -b html -D language=en $DOCS_DIRECTORY _build/html
  55   cache: *docs-cache
  56   artifacts:
  57     paths:
  58       - _build/html
  59   rules:
  60     - if: $CI_PIPELINE_SOURCE == "schedule" && $DOCS_SCHEDULE != "true"
  61       when: never
  62     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  63       changes:
  64         - $DOCS_DIRECTORY/**/*
  65     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  66     - if: $CI_COMMIT_BRANCH == $STABLE_BRANCH
  67
  68 docs-link-check:
  69   stage: test
  70   allow_failure: true
  71   needs: []
  72   image: python:3
  73   before_script:
  74     - *docs-before-script
  75   script: |
  76       sphinx-build -T -b linkcheck $DOCS_DIRECTORY _build/linkcheck
  77   cache: *docs-cache
  78   artifacts:
  79     paths:
  80       - _build/linkcheck
  81   rules:
  82     - if: $CI_PIPELINE_SOURCE == "schedule" && $DOCS_SCHEDULE != "true"
  83       when: never
  84     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  85       changes:
  86         - $DOCS_DIRECTORY/**/*
  87     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  88     - if: $CI_COMMIT_BRANCH == $STABLE_BRANCH
  89
  90 pages:
  91   stage: deploy
  92   image: python:3
  93   script: |
  94       mkdir public
  95       mv _build/html/* public/
  96   artifacts:
  97     paths:
  98       - public
  99   rules:
 100     - if: $CI_PIPELINE_SOURCE == "schedule"
 101       when: never
 102     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 103       changes:
 104         - $DOCS_DIRECTORY/**/*