{"thread":{"id":"45658","subject":"[PATCH v1 0/3] travis-ci: build docs with asciidoctor","startedAt":"2017-04-11T08:33:39Z","lastAt":"2017-04-18T15:05:03Z","messageCount":8,"participants":["Lars Schneider","Junio C Hamano","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"316554","messageId":"20170411083309.58315-1-larsxschneider@gmail.com","threadId":"45658","inReplyTo":null,"subject":"[PATCH v1 0/3] travis-ci: build docs with asciidoctor","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-04-11T08:33:06Z","receivedAt":"2017-04-11T08:33:39Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"Hi,\n\nthis is a mini series to build the documentation with asciidoctor in\naddition to asciidoc on Travis-CI.\n\nCheers,\nLars\n\nBase Ref: master\nWeb-Diff: https://github.com/larsxschneider/git/commit/88070fccc8\nCheckout: git fetch https://github.com/larsxschneider/git travisci/asciidoctor-v1 && git checkout 88070fccc8\n\nLars Schneider (3):\n travis-ci: build documentation with AsciiDoc and Asciidoctor\n travis-ci: parallelize documentation build\n travis-ci: unset compiler for jobs that do not need one\n\n .travis.yml | 5 +++--\n ci/test-documentation.sh | 10 +++++++++-\n 2 files changed, 12 insertions(+), 3 deletions(-)\n\n\nbase-commit: b14f27f91770e0f99f64135348977a0ce1c7993a\n--\n2.12.2\n\n"},{"id":"316555","messageId":"20170411083309.58315-2-larsxschneider@gmail.com","threadId":"45658","inReplyTo":"20170411083309.58315-1-larsxschneider@gmail.com","subject":"[PATCH v1 1/3] travis-ci: build documentation with AsciiDoc and Asciidoctor","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-04-11T08:33:07Z","receivedAt":"2017-04-11T08:33:41Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"ec3366e introduced a knob to enable the use of Asciidoctor in addition\nto AsciiDoc. Build the documentation on TravisCI with this knob to\nreduce the likeliness of breaking Asciidoctor support in the future.\n\nSigned-off-by: Lars Schneider \n---\n .travis.yml | 2 +-\n ci/test-documentation.sh | 10 +++++++++-\n 2 files changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/.travis.yml b/.travis.yml\nindex 591cc57b80..c26f3bf789 100644\n--- a/.travis.yml\n+++ b/.travis.yml\n@@ -69,7 +69,7 @@ matrix:\n - asciidoc\n - xmlto\n before_install:\n- before_script:\n+ before_script: gem install asciidoctor\n script: ci/test-documentation.sh\n after_failure:\n \ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex 579d540d32..e47d2ea611 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -7,8 +7,16 @@ set -e\n \n make check-builtins\n make check-docs\n-make doc\n \n+# Build docs with AsciiDoc\n+make doc\n test -s Documentation/git.html\n test -s Documentation/git.xml\n test -s Documentation/git.1\n+grep '\n---\n ci/test-documentation.sh | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nindex e47d2ea611..81f123e68d 100755\n--- a/ci/test-documentation.sh\n+++ b/ci/test-documentation.sh\n@@ -9,7 +9,7 @@ make check-builtins\n make check-docs\n \n # Build docs with AsciiDoc\n-make doc\n+make --jobs=2 doc\n test -s Documentation/git.html\n test -s Documentation/git.xml\n test -s Documentation/git.1\n@@ -17,6 +17,6 @@ grep '\n---\n .travis.yml | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/.travis.yml b/.travis.yml\nindex c26f3bf789..e5e7c3edd7 100644\n--- a/.travis.yml\n+++ b/.travis.yml\n@@ -41,6 +41,7 @@ matrix:\n include:\n - env: Linux32\n os: linux\n+ compiler:\n services:\n - docker\n before_install:\n@@ -62,7 +63,7 @@ matrix:\n # root@container:/# /usr/src/git/ci/run-linux32-build.sh\n - env: Documentation\n os: linux\n- compiler: clang\n+ compiler:\n addons:\n apt:\n packages:\n-- \n2.12.2\n\n"},{"id":"316796","messageId":"xmqq37dcorr7.fsf@gitster.mtv.corp.google.com","threadId":"45658","inReplyTo":"20170411083309.58315-1-larsxschneider@gmail.com","subject":"Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-13T22:41:00Z","receivedAt":"2017-04-13T22:41:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lars Schneider writes:\n\n> this is a mini series to build the documentation with asciidoctor in\n> addition to asciidoc on Travis-CI.\n\nOverall, this looks sensible. I didn't spot anything questionable\nother than a minor style nit, i.e. write these\n\n make doc USE_ASCIIDOCTOR=1\n make -j2 doc USE_ASCIIDOCTOR=1\n\nmore like this\n\n make USE_ASCIIDOCTOR=1 doc\n make -j2 USE_ASCIIDOCTOR=1 doc\n\nHaving said that, I wonder if we get some interesting results out of\nbuilding the documentation twice, though. By looking at the Travis\nlog with timestamps, we probably can see how long each build takes,\nbut that is much less interesting than learning if new versions of\ntext used mark-up that does not format correctly on one or the other\n(i.e. catch documentation breakage early in each CI run), for\nexample. I have an impression that neither AsciiDoc nor AsciiDoctor\n\"fails\" in an obvious way that \"make\" can notice (i.e. they often\njust silently produce nonsense output when fed a malformed input\ninstead).\n\nThanks.\n"},{"id":"317085","messageId":"63CA5B3A-8AEA-473B-9F4C-86C2BBB0530F@gmail.com","threadId":"45658","inReplyTo":"xmqq37dcorr7.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-04-18T08:32:59Z","receivedAt":"2017-04-18T08:33:30Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 14. Apr 2017, at 00:41, Junio C Hamano wrote:\n> \n> Lars Schneider writes:\n> \n>> this is a mini series to build the documentation with asciidoctor in\n>> addition to asciidoc on Travis-CI.\n> \n> Overall, this looks sensible. I didn't spot anything questionable\n> other than a minor style nit, i.e. write these\n> \n> make doc USE_ASCIIDOCTOR=1\n> make -j2 doc USE_ASCIIDOCTOR=1\n> \n> more like this\n> \n> make USE_ASCIIDOCTOR=1 doc\n> make -j2 USE_ASCIIDOCTOR=1 doc\n\nOK! I'll change it and send a new round next week.\n\n> Having said that, I wonder if we get some interesting results out of\n> building the documentation twice, though. By looking at the Travis\n> log with timestamps, we probably can see how long each build takes,\n> but that is much less interesting than learning if new versions of\n> text used mark-up that does not format correctly on one or the other\n> (i.e. catch documentation breakage early in each CI run), for\n> example. I have an impression that neither AsciiDoc nor AsciiDoctor\n> \"fails\" in an obvious way that \"make\" can notice (i.e. they often\n> just silently produce nonsense output when fed a malformed input\n> instead).\n\nTrue! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?\n\nIn 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?\n\nThanks,\nLars\n"},{"id":"317095","messageId":"20170418104411.hdkzh3psvej63tqw@genre.crustytoothpaste.net","threadId":"45658","inReplyTo":"63CA5B3A-8AEA-473B-9F4C-86C2BBB0530F@gmail.com","subject":"Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-04-18T10:44:11Z","receivedAt":"2017-04-18T10:44:23Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Tue, Apr 18, 2017 at 10:32:59AM +0200, Lars Schneider wrote:\n> \n> > On 14. Apr 2017, at 00:41, Junio C Hamano wrote:\n> > Having said that, I wonder if we get some interesting results out of\n> > building the documentation twice, though. By looking at the Travis\n> > log with timestamps, we probably can see how long each build takes,\n> > but that is much less interesting than learning if new versions of\n> > text used mark-up that does not format correctly on one or the other\n> > (i.e. catch documentation breakage early in each CI run), for\n> > example. I have an impression that neither AsciiDoc nor AsciiDoctor\n> > \"fails\" in an obvious way that \"make\" can notice (i.e. they often\n> > just silently produce nonsense output when fed a malformed input\n> > instead).\n> \n> True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?\n\nAsciidoctor isn't very strict about questionable items. If you want\nthat behavior, you'd want to check for output to standard error during\nthe make process, as Asciidoctor uses Ruby's warn function.\n\nOne of the things I've wanted to do is to make it able to be strict, but\nthat requires a lot of refactoring work that I just haven't gotten\naround to.\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"317110","messageId":"D9F45212-91F7-4BB1-A0EC-74A84DA81860@gmail.com","threadId":"45658","inReplyTo":"20170418104411.hdkzh3psvej63tqw@genre.crustytoothpaste.net","subject":"Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2017-04-18T15:03:50Z","receivedAt":"2017-04-18T15:05:03Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 18. Apr 2017, at 12:44, brian m. carlson wrote:\n> \n>> On Tue, Apr 18, 2017 at 10:32:59AM +0200, Lars Schneider wrote:\n>> \n>>> On 14. Apr 2017, at 00:41, Junio C Hamano wrote:\n>>> Having said that, I wonder if we get some interesting results out of\n>>> building the documentation twice, though. By looking at the Travis\n>>> log with timestamps, we probably can see how long each build takes,\n>>> but that is much less interesting than learning if new versions of\n>>> text used mark-up that does not format correctly on one or the other\n>>> (i.e. catch documentation breakage early in each CI run), for\n>>> example. I have an impression that neither AsciiDoc nor AsciiDoctor\n>>> \"fails\" in an obvious way that \"make\" can notice (i.e. they often\n>>> just silently produce nonsense output when fed a malformed input\n>>> instead).\n>> \n>> True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?\n> \n> Asciidoctor isn't very strict about questionable items. If you want\n> that behavior, you'd want to check for output to standard error during\n> the make process, as Asciidoctor uses Ruby's warn function.\n\nThat sounds good. I'll check stderr in the next iteration!\n\nThanks,\nLars"}]}