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