Run doctests in CI

.ci/test-cli.sh → .ci/check-cli.sh

@@ -2,7 +2,7 @@
 
 # This script gets called from CI to run minimal tests on the sagemath image.
 
-# Usage: ./test-cli.sh IMAGE-NAME
+# Usage: ./check-cli.sh IMAGE-NAME
 
 # ****************************************************************************
 # Copyright (C) 2018 Julian Rüth <julian.rueth@fsfe.org>

.ci/test-dev.sh → .ci/check-dev.sh

@@ -4,7 +4,7 @@
 # This script expects a single argument, the full name of the docker image to
 # test.
 
-# Usage: ./test-dev.sh IMAGE-NAME
+# Usage: ./check-dev.sh IMAGE-NAME
 
 # ****************************************************************************
 # Copyright (C) 2018 Julian Rüth <julian.rueth@fsfe.org>

.ci/test-jupyter.sh → .ci/check-jupyter.sh

@@ -3,7 +3,7 @@
 # This script gets called from CI to run minimal tests on the sagemath-jupyter
 # image.
 
-# Usage: ./test-jupyter.sh IMAGE-NAME [HOST]
+# Usage: ./check-jupyter.sh IMAGE-NAME [HOST]
 
 # ****************************************************************************
 # Copyright (C) 2018 Julian Rüth <julian.rueth@fsfe.org>

.ci/pull-dockerhub.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# This script gets called from CI to pull the Sage docker images that were
+# built during the "build" phase to pull to the connected docker daemon
+# (likely a docker-in-docker.)
+# This script expects a single parameter, the base name of the docker image
+# such as sagemath or sagemath-dev.
+# The variable $DOCKER_IMAGE is set to the full name of the pulled image;
+# source this script to use it.
+
+# ****************************************************************************
+# Copyright (C) 2018 Julian Rüth <julian.rueth@fsfe.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+# http://www.gnu.org/licenses/
+# ****************************************************************************
+
+set -ex
+
+# Pull the built images from the dockerhub registry and give them the original
+# names they had after built.
+# We require $DOCKER_USER and $SECRET_DOCKER_PASS to be set. Otherwise we would
+# be pulling some stale images here. (Sadly, CircleCI does not provide us with
+# an integrated container registry like GitLab does.)
+if [ -z "$DOCKER_USER" -o -z "$SECRET_DOCKER_PASS" ]; then
+ echo "DOCKER_USER/SECRET_DOCKER_PASS variables have not been configured in your Continuous Integration setup. Not pulling as the images would not be the one that has just been built."
+fi
+
+export DOCKER_IMAGE="$DOCKER_USER/$1:$DOCKER_TAG"
+docker pull $DOCKER_IMAGE

.ci/pull-gitlab.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 # This script gets called from CI to pull the Sage docker images that were
-# built during the "build" phase to pull all the connected docker daemon
+# built during the "build" phase to pull to the connected docker daemon
 # (likely a docker-in-docker.)
 # This script expects a single parameter, the base name of the docker image
 # such as sagemath or sagemath-dev.

.ci/setup-make-parallelity.sh

@@ -40,6 +40,7 @@ if [ -z "$RAMTHREADS" ]; then
  RAMTHREADS=1;
  fi
 fi
+
 if [ -z "$RAMTHREADS_DOCBUILD" ]; then
  RAMTHREADS_DOCBUILD=$(( `docker run docker cat /proc/meminfo | grep MemTotal | awk '{ print $2 }'` / 2097152 ))
  if [ $RAMTHREADS_DOCBUILD = 0 ];then

.ci/test-doctest.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+
+# This script gets called from CI to run doctests in the sagemath build
+
+# Usage: ./test-doctest.sh IMAGE-NAME --new|--short|--long
+
+# ****************************************************************************
+# Copyright (C) 2018 Julian Rüth <julian.rueth@fsfe.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+# http://www.gnu.org/licenses/
+# ****************************************************************************
+
+set -ex
+
+SETUP=":"
+
+case "$2" in
+ --new)
+ # We need an image that contains a .git directory as this is not
+ # contained in the sagemath image (and also not in sagemath-dev.)
+ # Note that we can not mount our own .git as the docker daemon might
+ # not run on the current host.
+ docker create --name sagemath-git-build "$1"
+ docker cp `pwd`/.git sagemath-git-build:/home/sage/sage/.git
+ docker commit sagemath-git-build sagemath-git
+ # Replace $1 so that the following code uses that image instead of the
+ # original "$1"
+ shift
+ set -- sagemath-git "$@"
+
+ SETUP='sudo apt-get update && sudo apt-get install -y git && \
+ cd /home/sage/sage && \
+ sudo chown -R sage:sage .git && \
+ git reset --hard && \
+ git reset `git describe --abbrev=0 --tags`'
+ DOCTEST_PARAMETERS="--long --new"
+ ;;
+ --short)
+ DOCTEST_PARAMETERS="--short --all"
+ ;;
+ --long)
+ DOCTEST_PARAMETERS="--long --all"
+ ;;
+ *)
+ exit 1
+ ;;
+esac
+
+docker run "$1" "$SETUP && \
+ (sage -tp $DOCTEST_PARAMETERS || \
+ (echo Some tests failed. Retrying only the failed tests. && sage -tp --failed $DOCTEST_PARAMETERS) || \
+ (echo Some tests failed. Retrying only the failed tests. && sage -tp --failed $DOCTEST_PARAMETERS))"

.circleci/config.yml

@@ -13,7 +13,7 @@
 
 version: 2
 jobs:
- build-test-release: &build-test-release
+ build-check-release: &build-check-release
  docker:
  - image: docker:latest
  environment:
@@ -34,17 +34,17 @@ jobs:
  name: test-dev
  command: |
  . .circleci/before-script.sh
- .ci/test-dev.sh $DOCKER_IMAGE_DEV
+ .ci/check-dev.sh $DOCKER_IMAGE_DEV
  - run: &test-cli
  name: test-cli
  command: |
  . .circleci/before-script.sh
- .ci/test-cli.sh $DOCKER_IMAGE_CLI
+ .ci/check-cli.sh $DOCKER_IMAGE_CLI
  - run: &test-jupyter
  name: test-jupyter
  command: |
  . .circleci/before-script.sh
- .ci/test-jupyter.sh $DOCKER_IMAGE_CLI localhost
+ .ci/check-jupyter.sh $DOCKER_IMAGE_CLI localhost
  - run: &release
  # The docker commands sometimes take a while to produce output
  no_output_timeout: 30m
@@ -54,36 +54,82 @@ jobs:
  # Push docker images to dockerhub if a dockerhub user has been configured
  .ci/push-dockerhub.sh sagemath-dev
  .ci/push-dockerhub.sh sagemath
- build-from-latest-test-release:
- <<: *build-test-release
- build-from-clean-test-release:
- <<: *build-test-release
+ build-from-latest-check-release:
+ <<: *build-check-release
+ build-from-clean-check-release:
+ <<: *build-check-release
  environment:
  ARTIFACT_BASE: source-clean
+ doctest: &doctest
+ docker:
+ - image: docker:latest
+ steps:
+ - run: apk --update add git openssh
+ - checkout
+ - setup_remote_docker
+ - run:
+ name: doctest
+ command: |
+ . .circleci/before-script.sh
+ . .ci/pull-dockerhub.sh sagemath
+ .ci/test-doctest.sh "$DOCKER_IMAGE" $DOCTEST_FLAVOUR
+ doctest-new:
+ <<: *doctest
+ environment:
+ # For the --new tests to work we need the .git directory which is only in the -dev image
+ DOCTEST_FLAVOUR: --new
+ doctest-short:
+ <<: *doctest
+ environment:
+ DOCTEST_FLAVOUR: --short
+ doctest-long:
+ <<: *doctest
+ environment:
+ DOCTEST_FLAVOUR: --long
 
 workflows:
  version: 2
  build-branch-from-clean:
  jobs:
- - build-from-clean-test-release:
+ - build-from-clean-check-release:
  filters:
  branches:
  only:
  - master
  - develop
+ - doctest-long:
+ requires:
+ - build-from-clean-check-release
  build-tag-from-clean:
  jobs:
- - build-from-clean-test-release:
+ - build-from-clean-check-release:
  filters:
  branches:
  ignore: /.*/
  tags:
  only: /.*/
+ - doctest-long:
+ requires:
+ - build-from-clean-check-release
  build-branch-from-latest:
  jobs:
- - build-from-latest-test-release:
+ - build-from-latest-check-release:
  filters:
  branches:
  ignore:
  - master
  - develop
+ - doctest-new:
+ requires:
+ - build-from-latest-check-release
+ - doctest-short:
+ requires:
+ - build-from-latest-check-release
+ - doctest-long-approval:
+ type: approval
+ requires:
+ - doctest-short
+ - doctest-new
+ - doctest-long:
+ requires:
+ - doctest-long-approval

.gitlab-ci.yml

@@ -36,13 +36,16 @@
 
 # If you want to provide your own runners, make sure to tag them as follows:
 # * "big" (60GB of disk space are available) to make build-from-clean pass.
+# * "long", enough resources to run long doctest, i.e., at least 5 CPU hours
 
 image: docker:latest
 
 stages:
  - build
- - test
+ - check
  - release
+ - test
+ - test-long
 
 variables:
  DOCKER_TAG: $CI_COMMIT_REF_NAME
@@ -90,6 +93,7 @@ build-from-latest: &build
  - gitlab-build-docker.log
  expire_in: 1 month
  script:
+ - set -o pipefail
  - apk --update add coreutils
  # The output of the build can get larger than gitlab.com's limit; only print the first 3MB (and the last 80 lines.)
  - .ci/build-docker.sh | tee gitlab-build-docker.log | .ci/head-tail.sh 3145728
@@ -125,23 +129,44 @@ build-from-clean:
  # So let's try three times before we give up.
  retry: 2
 
-test-dev:
- stage: test
+check-dev:
+ stage: check
  script:
  - . .ci/pull-gitlab.sh sagemath-dev
- - sh .ci/test-dev.sh "$DOCKER_IMAGE"
+ - sh .ci/check-dev.sh "$DOCKER_IMAGE"
 
-test-cli:
+check-cli:
+ stage: check
+ script:
+ - . .ci/pull-gitlab.sh sagemath
+ - sh .ci/check-cli.sh "$DOCKER_IMAGE"
+
+check-jupyter:
+ stage: check
+ script:
+ - . .ci/pull-gitlab.sh sagemath
+ - sh .ci/check-jupyter.sh "$DOCKER_IMAGE" docker
+
+test-doctest-new:
  stage: test
  script:
  - . .ci/pull-gitlab.sh sagemath
- - sh .ci/test-cli.sh "$DOCKER_IMAGE"
+ - sh .ci/test-doctest.sh "$DOCKER_IMAGE" --new
 
-test-jupyter:
+test-doctest-short:
  stage: test
  script:
  - . .ci/pull-gitlab.sh sagemath
- - sh .ci/test-jupyter.sh "$DOCKER_IMAGE" docker
+ - sh .ci/test-doctest.sh "$DOCKER_IMAGE" --short
+
+test-doctest-long:
+ stage: test-long
+ tags:
+ # runner is going to run for at least 5 CPU hours
+ - long
+ script:
+ - . .ci/pull-gitlab.sh sagemath
+ - sh .ci/test-doctest.sh "$DOCKER_IMAGE" --long
 
 # Pushes the built images to Docker Hub if the Settings -> CI/CD -> Secret
 # variables DOCKER_USER and SECRET_DOCKER_PASS have been set up.

docker/entrypoint-dev.sh

@@ -1,4 +1,4 @@
 #!/bin/bash
 set -e
 make build
-exec "$@"
+exec sh -c "$*"

src/sage/misc/sagedoc.py

@@ -798,9 +798,7 @@ def _search_src_or_doc(what, string, extra1='', extra2='', extra3='',
 
  The examples are nice, but marking them "random" means we're not
  really testing if the function works, just that it completes. These
- tests aren't perfect, but are reasonable.
-
- ::
+ tests aren't perfect, but are reasonable::
 
  sage: from sage.misc.sagedoc import _search_src_or_doc # optional - dochtml
  sage: len(_search_src_or_doc('src', r'matrix\(', 'incidence_structures', 'self', 'combinat', interact=False).splitlines()) > 1 # optional - dochtml