Docs: Fix a table start to align with the stop

[nik9000]

Asciidoctor is a bit pickier about start and end delimiter and complains
about this table because the start line has more =s than the end line.
This removes =s from the start until it lines up with the end.

[nik9000]

It looks like that file is generated. I'll dig.

[webmat]

@nik9000 Thanks for this PR :-)

Was this the only issue wrt Asciidoctor?

By the way I'd love to switch over to Asciidoctor sooner than later, or at least make it another Make target, so it's easy to keep tabs on compatibility / add as separate CI task & so on.

Your guidance was simply to call the script without the .pl extension, with the same params, is that correct?

[nik9000]

Was this the only issue wrt Asciidoctor?

The Asciidoctor issues show up in two waves:

• Issues that cause the build to emit warnings that cause us to fail building the document. This change falls into this category.
• Differences between the output with Asciidoctor compared to AsciiDoc. I'll make make a comment on Switch the ECS docs to Asciidoctor docs#813 when I have a diff to look at. Sometimes the differences are good, sometimes they are bad.

I've built a little suite of AsciiDoctor customizations to prevent some of these issues but some things have ended up being simpler to fix in the docs themselves.

By the way I'd love to switch over to Asciidoctor sooner than later, or at least make it another Make target, so it's easy to keep tabs on compatibility / add as separate CI task & so on.

So! Some things:

1. I can make a PR job that builds your docs automatically. It'd look like https://elasticsearch-ci.elastic.co/view/Docs/job/elastic+docs+apm-agent-python+pull-request/ . It wouldn't build the docs with asciidoctor because we haven't switched the config to asciidoctor. But once we put out mind to asciidoctor support we tend to be able to make the switch pretty quickly. At some point I'd like every project to use a CI job like this because I can make sweeping improvements for all projects by modifying a single job.
2. I totally support making your own make target for Asciidoctor! This is the command that I used to build the docs with asciidoctor:

./docs/build_docs --doc ./ecs/docs/index.asciidoc --asciidoctor --chunk 1 --open --out ./built_docs

--open will serve the docs for easy preview but will cause the process to block forever so you probably don't want it in your normal make target.

If you are ok with me making a PR job for you then you don't need to build the docs are part of your normal PR builds. You certainly can keep doing it though. And having a make target to use locally is super convenient.

Your guidance was simply to call the script without the .pl extension, with the same params, is that correct?

There are two related things going on:

1. Calling the script without .pl will call the "dockerized" version of the docs build. Instead of requiring perl and some perl modules and ruby and stuff it requires docker and python. At the moment it builds the docker image on the fly to reduce the number of moving parts involved with changing the dependencies. When you are developing locally this amounts to a minute or two hit every once in a while. In CI we pre-build the image.
2. Adding the --asciidoctor flag will build the docs with Asciidoctor. We don't support building with Asciidoctor outside of the docker image, mostly because it adds additional dependencies (ruby and some gems). We'll likely add other dependencies and docker makes this a thing that "just happens" when I merge changes to the Dockerfile.

[webmat]

Yes, we're using --open in the build target for developer convenience, and we're overriding it in the CI job

A PR to build the docs with based on your template/script as you're showing me for APM would be very welcome as well. ECS is a simple project and I can't see a reason I'd say no to that :-)

Note however that the main CI for ECS is currently Travis CI. Not sure if this changes the amount of work you have to do for this doc generation Jenkins job?

[nik9000]

Not sure if this changes the amount of work you have to do for this doc generation Jenkins job?

I don't think it does.

[nik9000]

Thanks for the merge @webmat!

[nik9000]

@webmat, should I do anything for the backport?

[webmat]

@nik9000 I could have sworn I had done it already. I'll go do it, all I'll need from you is a thumbs up ;-)

Thanks for the ping