.gitlab-ci.yml

# Other images are possible, such as usgs images; all seem to have the SSL issue with pip, requiring workaround.
image: continuumio/miniconda3

# Defining the stages for the CI/CD pipeline.
# Commenting them out will disable them.
stages:
  - build
  - deploy
  - testing

# Define where to store cached info for this pipeline
# Cached information is available to this pipeline AND to other pipelines.
cache:
  paths:
    - cache/

# This before_script builds pyhat on the remote CI resource, which will be used in later jobs.
# Not all of these 'before_script' steps may be absolutely necessary for each pipeline job.
# However, tailoring each job gets complicated and leads to duplication within this script.
# These environment building steps should take less than 10 min.
before_script:
  # Python version for debugging
  - python --version

  # Check the TLS version, it should be >= v1.2
  - python -c "import requests; print(requests.get('https://www.howsmyssl.com/a/check', verify=False).json()['tls_version'])"

  # Run a repo update, so we can install the latest packages if/where needed
  - apt-get update

  # Check conda version, install latest
  - conda --version
  - conda update -n base -c defaults conda

  # Install tree which is necessary for documentation generation
  # The docker image (remote on Gitlab) also doesn't have this libGL.so.1,
  # so lets get that installed. It's necessary for gui functionality. Although
  # we don't test the gui remotely, not having this will throw lots of warnings.
  - apt-get -y install tree libgl1

  # Globally dodge SSL issues with pip in the Gitlab CI/CD pipeline.
  # This is a band-aid. Ideally, the runner/build container needs to have the proper certs.
  - python -m pip config set global.trusted-host=pypi.org files.pythonhosted.org

  # Create the pyhat environment, which install all dependencies of PyHAT.
  # Note: Env building often fails hen urllib3 tries to fetch repodata
  # Regarding the runner is the temporary fix. Sometimes several restarts are needed.
  # If it hangs more than a few min on the urllib3 call, it probably needs restarting.
  # You will only see the urllib3 call if you have -vvv on the next line. Otherwise, it
  # will show up on the 'libmamba Reading repodata.json file' step with the double
  # verbosity option. Triple verbosity tends to clog up the CI/CD logs.
  - conda env create -n pyhat -f environment.yml -vv

  # Set shell for conda
  - conda init bash
  - source /root/.bashrc

  # Activate the PyHAT conda environment such that the next stages (e.g. testing)
  # have access to the packages in this environment and the PyHAT modules.
  - conda activate pyhat

# Unit testing, runs parallel with lint testing
unit-test:
  stage: testing
  script:

    # Install testing packages.
    # This is not installed in the before_script; it's not relevant to users.
    - conda install --quiet pytest pytest-cov

    # Run the test on the entire branch
    - pytest --cov=libpyhat

  allow_failure: false

## Linting testing, runs parallel with unit testing
lint-test:
  stage: testing
  script:
    # Install flake8 for lint testing.
    # This is not installed in the before_script; it's not relevant to users.
    - pip install flake8

    # Run lint testing on the repo.
    # Some PEP8 errors are obsolete when using the Black formatter
    - flake8

  allow_failure: false

### Old documentation generation and deployment step
## The stage must be named deploy and the name of the stage needs to be 'pages'
#pages:
#  stage: deploy
#  script:
#
#    # Install sphinx, the sphinx notebook parser, and the readthedocs theme
#    - pip install -U sphinx nbsphinx sphinx-rtd-theme
#
#    # Generate rst's for each module
#    - sphinx-apidoc -o docs .
#
#    # Build html-based documentation
#    - sphinx-build -b html docs public
#
#  # Artifacts are files generated by the pipeline, docs in this case
#  artifacts:
#    # Path must be set to public so that GitLab pages recognizes it
#    paths:
#      - public
#    only:
#      - dev
#  when: always

#workflow:
#  rules: # disable tag pipelines and duplicate MR pipelines
#    - if: $CI_COMMIT_BRANCH

# Set some environment variables for the following pipeline jobs.
variables:
  # The ephemeral branch path defines where we temporarily store documentation
  # for non-default branches. This documentation is not meant to be perused by
  # the user, but by the development team during documentation iteration.
  EPHEMERAL_BRANCHES_PATH: preview

# Documentation generation and deployment, including for ephemeral branches.
# Runs after testing steps
pages:
  stage: build
  image: continuumio/miniconda3
  cache:
    key: gitlab-pages
    paths: [ public ]
  script:
    # CURRENT_CONTENT_PATH is defined in rules
    # Its value is different between main branch and ephemeral branches
    - mkdir -p public/$CURRENT_CONTENT_PATH && ls public/$CURRENT_CONTENT_PATH/..

    - echo $CURRENT_CONTENT_PATH
    - echo $CI_DEFAULT_BRANCH
    - echo $CI_COMMIT_BRANCH
    - echo $EPHEMERAL_BRANCHES_PATH

    # Uncomment after merging with the default branch
    - | # Avoid deleting main branch content when cache has been erased
      if [ "$CI_COMMIT_BRANCH" != "$CI_DEFAULT_BRANCH" ] && [ ! -d public/$CI_DEFAULT_BRANCH ]; then
        echo -e "💥\e[91;1m Unable to retrieve $CI_DEFAULT_BRANCH generated files from cache ; please regenerate $CI_DEFAULT_BRANCH files first\e[0m"
        exit 1
      fi

    # Remove the last version of the current branch.
    - rm -rf public/$CURRENT_CONTENT_PATH || true

    # Generate rst's (document markup files) for each module in PyHAT.
    - sphinx-apidoc -o docs .

    # Build html-based documentation.
    - sphinx-build -b html docs build-docs

    # Let's figure out if anything is being generated..
    - ls build-docs/
    - ls public/

    # Move the build-docs directory to the public directory, where it
    # can be published to the documentation website on Gitlab.
    # Change the folder name to one with the pipeline identifier in it.
    - if [ ! -d "public/$CURRENT_CONTENT_PATH" ]; then
    -   mv --verbose build-docs public/$CURRENT_CONTENT_PATH
    - fi

    # Move to where the ephemeral branches are stored.
    - cd public/$EPHEMERAL_BRANCHES_PATH

    # Generate a root HTML listing all previews for easier access.
    # This will not be visible at the main documentation site. The user
    # will need to change the website address by hand to access them.
    # They need to append '/preview' to the pages link.
    - tree -d -H '.' -L 1 --noreport --charset utf-8 -T "Versions" -o index.html
  environment:
    name: pages/$CI_COMMIT_BRANCH
    action: start
    url: $CI_PAGES_URL/$CURRENT_CONTENT_PATH
    # If the pages-clean-preview function is performed manually, then this job will stop
    on_stop: pages-clean-preview
  rules:
    # 'main branch' is exposed at GitLab Pages root
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        CURRENT_CONTENT_PATH: "."
    # other (short-lived) branches generation are exposed in 'EPHEMERAL_BRANCHES_PATH/branch-name-sanitized' sub path
    - variables:
        CURRENT_CONTENT_PATH: $EPHEMERAL_BRANCHES_PATH/$CI_COMMIT_REF_SLUG
  artifacts:
    paths: [ public ]
    # Remove ephemeral branch documentation after some time
    expire_in: 24h

# This is a manual pipeline action that erases the ephemeral documentation
# of the current branch. Notice the hard-coded ephemeral branch folder to delete.
pages-clean-preview:
  stage: build
  image: continuumio/miniconda3
  cache:
    key: gitlab-pages
    paths: [ public ]
  variables:
    GIT_STRATEGY: none # git files not available after branch deletion
    FOLDER_TO_DELETE: preview/$CI_COMMIT_BRANCH # an indirection to allow arbitrary deletion when launching this job
  script:
    - rm -rf public/$FOLDER_TO_DELETE
  environment:
    name: pages/$CI_COMMIT_BRANCH
    action: stop
  rules:
    # Don't allow the user to delete the default branch documentation.
    # Depending on the setup, this can refer to the 'dev' branch or 'main'.
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
      # Only let this step be performed manually in the pipeline management tool on GitLab.
      when: manual
      allow_failure: true