patch, 3 partstravis-ci: build docs with asciidoctor

Hi,

this is a mini series to build the documentation with asciidoctor in addition to asciidoc on Travis-CI.

Cheers, Lars

Base Ref: master
Web-Diff: https://github.com/larsxschneider/git/commit/88070fccc8
Checkout: git fetch https://github.com/larsxschneider/git travisci/asciidoctor-v1 && git checkout 88070fccc8

Lars Schneider (3):
  travis-ci: build documentation with AsciiDoc and Asciidoctor
  travis-ci: parallelize documentation build
  travis-ci: unset compiler for jobs that do not need one

 .travis.yml              |  5 +++--
 ci/test-documentation.sh | 10 +++++++++-
 2 files changed, 12 insertions(+), 3 deletions(-)

base-commit: b14f27f91770e0f99f64135348977a0ce1c7993a -- 2.12.2

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(-)

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(-)

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(-)

Lars Schneider <larsxschneider@gmail.com> writes:

Overall, this looks sensible. I didn't spot anything questionable other than a minor style nit, i.e. write these

    make doc USE_ASCIIDOCTOR=1
    make -j2 doc USE_ASCIIDOCTOR=1

more like this

    make USE_ASCIIDOCTOR=1 doc
    make -j2 USE_ASCIIDOCTOR=1 doc

Having said that, I wonder if we get some interesting results out of building the documentation twice, though. By looking at the Travis log with timestamps, we probably can see how long each build takes, but that is much less interesting than learning if new versions of text used mark-up that does not format correctly on one or the other (i.e. catch documentation breakage early in each CI run), for example. I have an impression that neither AsciiDoc nor AsciiDoctor "fails" in an obvious way that "make" can notice (i.e. they often just silently produce nonsense output when fed a malformed input instead).

Thanks.

OK! I'll change it and send a new round next week.

True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?

In addition, we could push the resulting documentation somewhere. However, that would still require a human to look at it. Do you think that could have value?

Thanks, Lars

On Tue, Apr 18, 2017 at 10:32:59AM +0200, Lars Schneider wrote:

Asciidoctor isn't very strict about questionable items. If you want that behavior, you'd want to check for output to standard error during the make process, as Asciidoctor uses Ruby's warn function.

One of the things I've wanted to do is to make it able to be strict, but that requires a lot of refactoring work that I just haven't gotten around to.

That sounds good. I'll check stderr in the next iteration!

Thanks, Lars