[PATCH v1 0/3] travis-ci: build docs with asciidoctor

[PATCH v1 0/3] travis-ci: build docs with asciidoctor

[Lars Schneider]

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

[PATCH v1 1/3] travis-ci: build documentation with AsciiDoc and Asciidoctor

[Lars Schneider]

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..e47d2ea611 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 doc USE_ASCIIDOCTOR=1
+test -s Documentation/git.html
+grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
-- 
2.12.2

[PATCH v1 2/3] travis-ci: parallelize documentation build

[Lars Schneider]

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 e47d2ea611..81f123e68d 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 doc USE_ASCIIDOCTOR=1
+make --jobs=2 doc USE_ASCIIDOCTOR=1
 test -s Documentation/git.html
 grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
-- 
2.12.2

[PATCH v1 3/3] travis-ci: unset compiler for jobs that do not need one

[Lars Schneider]

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

Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor

[Junio C Hamano]

Lars Schneider <larsxschneider@gmail.com> writes:

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

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.

Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor

[Lars Schneider]

> On 14. Apr 2017, at 00:41, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Lars Schneider <larsxschneider@gmail.com> writes:
> 
>> this is a mini series to build the documentation with asciidoctor in
>> addition to asciidoc on Travis-CI.
> 
> 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

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

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

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

Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1470 bytes --]

On Tue, Apr 18, 2017 at 10:32:59AM +0200, Lars Schneider wrote:
> 
> > On 14. Apr 2017, at 00:41, Junio C Hamano <gitster@pobox.com> wrote:
> > 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).
> 
> True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?

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.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor

[Lars Schneider]

> On 18. Apr 2017, at 12:44, brian m. carlson <sandals@crustytoothpaste.net> wrote:
> 
>> On Tue, Apr 18, 2017 at 10:32:59AM +0200, Lars Schneider wrote:
>> 
>>> On 14. Apr 2017, at 00:41, Junio C Hamano <gitster@pobox.com> wrote:
>>> 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).
>> 
>> True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?
> 
> 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.

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

Thanks,
Lars