# [PATCH v2 0/4] travis-ci: build docs with asciidoctor

6 messages from 2017-04-26 to 2017-04-27. Participants: Lars Schneider, Junio C Hamano.
Thread: https://gitlist.dev/t/45804

## Lars Schneider, 2017-04-26 19:15

Subject: [PATCH v2 0/4] travis-ci: build docs with asciidoctor
Message-ID: <20170426191545.27552-1-larsxschneider@gmail.com>
URL: https://gitlist.dev/e/20170426191545.27552-1-larsxschneider%40gmail.com

```
Hi,

changes since v1:

* check Asciidoctor stderr output (Brian)
  http://public-inbox.org/git/20170418104411.hdkzh3psvej63tqw@genre.crustytoothpaste.net/

* fix make style nit (Junio)
  http://public-inbox.org/git/xmqq37dcorr7.fsf@gitster.mtv.corp.google.com/


Thanks,
Lars

Base Ref: master
Web-Diff: https://github.com/larsxschneider/git/commit/315affa7c0
Checkout: git fetch https://github.com/larsxschneider/git travisci/asciidoctor-v2 && git checkout 315affa7c0
Interdiff (v1..v2):

diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
index 81f123e68d..6214e6acb4 100755
--- a/ci/test-documentation.sh
+++ b/ci/test-documentation.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 #
 # Perform sanity checks on documentation and build it.
 #
@@ -9,7 +9,8 @@ make check-builtins
 make check-docs

 # Build docs with AsciiDoc
-make --jobs=2 doc
+make --jobs=2 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)
+! test -s stderr.log
 test -s Documentation/git.html
 test -s Documentation/git.xml
 test -s Documentation/git.1
@@ -17,6 +18,8 @@ grep '<meta name="generator" content="AsciiDoc ' Documentation/git.html

 # Build docs with AsciiDoctor
 make clean
-make --jobs=2 doc USE_ASCIIDOCTOR=1
+make --jobs=2 USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)
+sed '/^GIT_VERSION = / d' stderr.log
+! test -s stderr.log
 test -s Documentation/git.html
 grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html

\0

Lars Schneider (4):
  travis-ci: build documentation with AsciiDoc and Asciidoctor
  travis-ci: parallelize documentation build
  travis-ci: check AsciiDoc/AsciiDoctor stderr output
  travis-ci: unset compiler for jobs that do not need one

 .travis.yml              |  5 +++--
 ci/test-documentation.sh | 15 +++++++++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)


base-commit: b14f27f91770e0f99f64135348977a0ce1c7993a
--
2.12.2


```

## Lars Schneider, 2017-04-26 19:15

Subject: [PATCH v2 1/4] travis-ci: build documentation with AsciiDoc and Asciidoctor
Message-ID: <20170426191545.27552-2-larsxschneider@gmail.com>
URL: https://gitlist.dev/e/20170426191545.27552-2-larsxschneider%40gmail.com
In-Reply-To: <20170426191545.27552-1-larsxschneider@gmail.com>

```
ec3366e introduced a knob to enable the use of Asciidoctor in addition
to AsciiDoc. Build the documentation on TravisCI with this knob to
reduce the likeliness of breaking Asciidoctor support in the future.

Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
---
 .travis.yml              |  2 +-
 ci/test-documentation.sh | 10 +++++++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 591cc57b80..c26f3bf789 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -69,7 +69,7 @@ matrix:
           - asciidoc
           - xmlto
       before_install:
-      before_script:
+      before_script: gem install asciidoctor
       script: ci/test-documentation.sh
       after_failure:
 
diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
index 579d540d32..bf23b2caea 100755
--- a/ci/test-documentation.sh
+++ b/ci/test-documentation.sh
@@ -7,8 +7,16 @@ set -e
 
 make check-builtins
 make check-docs
-make doc
 
+# Build docs with AsciiDoc
+make doc
 test -s Documentation/git.html
 test -s Documentation/git.xml
 test -s Documentation/git.1
+grep '<meta name="generator" content="AsciiDoc ' Documentation/git.html
+
+# Build docs with AsciiDoctor
+make clean
+make USE_ASCIIDOCTOR=1 doc
+test -s Documentation/git.html
+grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
-- 
2.12.2


```

## Lars Schneider, 2017-04-26 19:15

Subject: [PATCH v2 2/4] travis-ci: parallelize documentation build
Message-ID: <20170426191545.27552-3-larsxschneider@gmail.com>
URL: https://gitlist.dev/e/20170426191545.27552-3-larsxschneider%40gmail.com
In-Reply-To: <20170426191545.27552-1-larsxschneider@gmail.com>

```
The documentation job without parallelization takes ~10min on TravisCI.
With parallelization ("--jobs=2") it takes ~6min.

Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
---
 ci/test-documentation.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
index bf23b2caea..58962d668a 100755
--- a/ci/test-documentation.sh
+++ b/ci/test-documentation.sh
@@ -9,7 +9,7 @@ make check-builtins
 make check-docs
 
 # Build docs with AsciiDoc
-make doc
+make --jobs=2 doc
 test -s Documentation/git.html
 test -s Documentation/git.xml
 test -s Documentation/git.1
@@ -17,6 +17,6 @@ grep '<meta name="generator" content="AsciiDoc ' Documentation/git.html
 
 # Build docs with AsciiDoctor
 make clean
-make USE_ASCIIDOCTOR=1 doc
+make --jobs=2 USE_ASCIIDOCTOR=1 doc
 test -s Documentation/git.html
 grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
-- 
2.12.2


```

## Lars Schneider, 2017-04-26 19:15

Subject: [PATCH v2 3/4] travis-ci: check AsciiDoc/AsciiDoctor stderr output
Message-ID: <20170426191545.27552-4-larsxschneider@gmail.com>
URL: https://gitlist.dev/e/20170426191545.27552-4-larsxschneider%40gmail.com
In-Reply-To: <20170426191545.27552-1-larsxschneider@gmail.com>

```
`make` does not necessarily fail with an error code if
Asciidoc/AsciiDoctor encounters problems. Anything written to stderr
might be a better indicator for problems.

Ensure that nothing is written to stderr during a documentation build.

The redirects do not work in `sh`, therefore the script uses `bash`.
This shouldn't be a problem as the script is only executed on TravisCI.

Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
---
 ci/test-documentation.sh | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
index 58962d668a..6214e6acb4 100755
--- a/ci/test-documentation.sh
+++ b/ci/test-documentation.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 #
 # Perform sanity checks on documentation and build it.
 #
@@ -9,7 +9,8 @@ make check-builtins
 make check-docs
 
 # Build docs with AsciiDoc
-make --jobs=2 doc
+make --jobs=2 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)
+! test -s stderr.log
 test -s Documentation/git.html
 test -s Documentation/git.xml
 test -s Documentation/git.1
@@ -17,6 +18,8 @@ grep '<meta name="generator" content="AsciiDoc ' Documentation/git.html
 
 # Build docs with AsciiDoctor
 make clean
-make --jobs=2 USE_ASCIIDOCTOR=1 doc
+make --jobs=2 USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.log >&2)
+sed '/^GIT_VERSION = / d' stderr.log
+! test -s stderr.log
 test -s Documentation/git.html
 grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
-- 
2.12.2


```

## Lars Schneider, 2017-04-26 19:15

Subject: [PATCH v2 4/4] travis-ci: unset compiler for jobs that do not need one
Message-ID: <20170426191545.27552-5-larsxschneider@gmail.com>
URL: https://gitlist.dev/e/20170426191545.27552-5-larsxschneider%40gmail.com
In-Reply-To: <20170426191545.27552-1-larsxschneider@gmail.com>

```
TravisCI does not need to setup any compiler for the documentation
build. Clear the value to fix this.

The Linux32 build job does not define the compiler but it inherits the
value from the base job. Since it does not need the compiler either
because the build runs inside a Docker container we should clear this,
too.

Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
---
 .travis.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index c26f3bf789..e5e7c3edd7 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -41,6 +41,7 @@ matrix:
   include:
     - env: Linux32
       os: linux
+      compiler:
       services:
         - docker
       before_install:
@@ -62,7 +63,7 @@ matrix:
         # root@container:/# /usr/src/git/ci/run-linux32-build.sh
     - env: Documentation
       os: linux
-      compiler: clang
+      compiler:
       addons:
         apt:
           packages:
-- 
2.12.2


```

## Junio C Hamano, 2017-04-27 01:21

Subject: Re: [PATCH v2 3/4] travis-ci: check AsciiDoc/AsciiDoctor stderr output
Message-ID: <xmqqshkuprwj.fsf@gitster.mtv.corp.google.com>
URL: https://gitlist.dev/e/xmqqshkuprwj.fsf%40gitster.mtv.corp.google.com
In-Reply-To: <20170426191545.27552-4-larsxschneider@gmail.com>

```
Lars Schneider <larsxschneider@gmail.com> writes:

> Ensure that nothing is written to stderr during a documentation build.

I guess we'll know if any output to stderr is an error, or if there
are some informational output that would trigger failure from this
change soon enough.  Will queue.

Thanks.

```