From 71dd38ae5942b63eeef5dc3933af4d1cae7da371 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Fri, 15 Mar 2019 12:19:32 -0400 Subject: [PATCH] Switch APM Agent for NodeJS to Asciidoctor Switches the core of the docs build process from the no-longer-maintained AsciiDoc to the actively-maintained Asciidoctor. The resulting HTML is mostly the same but there are a few differences: 1. Spacing changes that the browser ignores 2. AsciiDoc adds `

` inside any empty table cell. Asciidoctor does not. 3. The automatically generated alt text for one of the images is different in Asciidoctor. I believe the Asciidoctor alt text is marginally better but I don't think automatically generated alt text is a good thing in general. 4. There is a particular table cell that seems to be changed like so: - ^2.0.0 || ^3.1.0 + \^2.0.0 || ^3.1.0 I think we can probably change the table cell in the docs after merging Asciidoctor. 5. One of the deprecation warnings looks a little sad: - Span started automatically by - - apm.startSpan() - + Span started automatically by <<apm-start-span I'm going to investigate this one further before we merge this. I expect Asciidoctor has a non-greedy regex instead of a greedy one. We might just have to work around this. This seems to be a rare thing. But I'll check! --- conf.yaml | 1 + doc_build_aliases.sh | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/conf.yaml b/conf.yaml index 10522e8e2e3f1..bbfb86995cd55 100644 --- a/conf.yaml +++ b/conf.yaml @@ -878,6 +878,7 @@ contents: tags: APM Node.js Agent/Reference subject: APM chunk: 1 + asciidoctor: true sources: - repo: apm-agent-nodejs diff --git a/doc_build_aliases.sh b/doc_build_aliases.sh index 1ca92ece0021b..241db3475e4a9 100644 --- a/doc_build_aliases.sh +++ b/doc_build_aliases.sh @@ -82,7 +82,7 @@ alias docbldamg='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/apm-server/docs/gu alias docbldamr='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/apm-server/docs/index.asciidoc --chunk 1' -alias docbldamn='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/apm-agent-nodejs/docs/index.asciidoc --chunk 1' +alias docbldamn='$GIT_HOME/docs/build_docs --asciidoctor --doc $GIT_HOME/apm-agent-nodejs/docs/index.asciidoc --chunk 1' alias docbldamp='$GIT_HOME/docs/build_docs.pl --doc $GIT_HOME/apm-agent-python/docs/index.asciidoc --chunk 1'