language-reference/.gitlab-ci.yml at master · aimms/language-reference · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
stages:
  - doc_test
  - doc_build
  - doc_deploy

.run_on_dockerhost: &run_on_dockerhost
  tags:
    - docker20
  image: "${DOCKER_ACCESS_URL}/other/dockerdev/documentation:latest"

# Two linkcheck runs, the same pair every AIMMS docs repo has: the gating one
# checks only links internal to this project, the informational one also checks
# external links and is allowed to fail. Splitting them is what keeps a rotted
# or bot-blocked third-party URL from turning the pipeline red.
linkcheck:
  <<: *run_on_dockerhost
  stage: doc_test
  variables:
    SPHINX_IGNORE_EXTERNAL_LINKS: "true"
  script:
    - sphinx-build -W --keep-going -b linkcheck . _build/linkcheck

linkcheck_external:
  <<: *run_on_dockerhost
  stage: doc_test
  script:
    - sphinx-build -W --keep-going -b linkcheck . _build/linkcheck
  allow_failure: true

build:
  <<: *run_on_dockerhost
  stage: doc_test
  script:
    - sphinx-build -W --keep-going -b html . _build/html

# Informational, unlike the gating spellcheck in documentation and how-to, and
# not yet meaningful: this conf.py sets neither spelling_word_list_filename nor
# spelling_filters, so the job runs without the AIMMS theme's shared word list
# and without ProperNounsFilter. A raw run on that basis flagged 131 files, a
# mix of AIMMS identifiers the checker cannot know and genuine typos. Wiring up
# the two settings the way how-to does is the prerequisite; only then is the
# remaining count worth acting on, and only then can allow_failure come off.
spellcheck:
  <<: *run_on_dockerhost
  stage: doc_test
  script:
    - sphinx-build -W --keep-going -b spelling . _build/spelling
  allow_failure: true

# Every branch gets its own parallel Pages deployment at:
#   <CI_PAGES_URL>/<branch-slug>/
build_staging:
  <<: *run_on_dockerhost
  stage: doc_build
  # Depend on the three gating checks by name rather than on the whole test
  # stage. Stage ordering alone would also make linkcheck_external a
  # prerequisite: it is allow_failure so it can never fail the pipeline, but the
  # stage would still wait for it to finish, and checking every external URL is
  # by far the slowest job here. spellcheck is listed even where it is
  # allow_failure - a needed job that fails but is allowed to does not block.
  needs:
    # artifacts: false on all three - this job rebuilds the HTML itself, so
    # downloading build's output would only waste transfer and risk
    # publishing stale pages, since sphinx-build does not delete output that
    # no longer has a source.
    - job: build
      artifacts: false
    - job: linkcheck
      artifacts: false
    - job: spellcheck
      artifacts: false
  rules:
    # Staging is for work in progress, so every branch gets its own Pages
    # prefix - develop included. master and main are excluded: they publish
    # through the production deploy jobs and must not also show up as a
    # staging deployment. Requiring CI_COMMIT_BRANCH at all also keeps tag
    # and merge-request pipelines out, since it is set only for branches.
    - if: $CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "main"
      when: never
    - if: $CI_COMMIT_BRANCH
      when: on_success
    - when: never
  # The "pages" keyword - not the job name - is what makes this a Pages job
  # (GitLab 17.9+). Keep it, or staging stops publishing.
  pages:
    path_prefix: "$CI_COMMIT_REF_SLUG"
    # Doc branches can stay open for months. Every push to the branch
    # republishes and resets this clock, so only branches that go quiet for a
    # full quarter expire - and re-running this job republishes them at the
    # same URL.
    expire_in: 3 months
  environment:
    name: docs-staging/$CI_COMMIT_REF_SLUG
    url: $CI_PAGES_URL
  script:
    - sphinx-build -b html . _build/html
    # Pages publishes the "public" directory at the repository root
    - rm -rf public
    - mv _build/html public
    - echo "Staging documentation published to ${CI_PAGES_URL}"
  artifacts:
    paths:
      - public

deploy:
  <<: *run_on_dockerhost
  stage: doc_deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: on_success
    - when: never
  script:
    - sphinx-build -b html . _build/html
    - python3 -msphinx.ext.intersphinx _build/html/objects.inv > _build/html/help_index_languagereference.txt
    - cp -r _build/html language-reference
    - az storage copy -s 'language-reference' --recursive --destination-container '$web' -- --overwrite=true --as-subdir=true
    - bash load_ssh_key_for_deploy.sh
    - rsync -rt --delete-excluded _build/html/ support@data.aimms.com:/home/aimms/www/documentation.aimms.com/language-reference