Switch the PHP client to Asciidoctor

[nik9000]

Switches the PHP client's doc to being built from Asciidoctor. The
resulting html has quite a few changes spacing changes that aren't
impactful and a couple of small changes that look fine visually. There
are a few changes to auto-generated IDs that we've grown to expect from
asciidoctor. They seem fine to me. Here is the diff:
https://gist.github.com/nik9000/72113b441f682b116b7b41a2b78baed6

[polyfractal]

I'll trust your judgment here and say 👍 :)

[nik9000]

I'll trust your judgment here and say +1 :)

Thanks! A few minutes after the build is done you should see the changes in the site!

[lcawl]

@polyfractal The changes seemed fine to me too. However, I think it is not a great idea long-term to rely on auto-generated IDs for all of the top pages in the book (e.g. the "_overview" in https://www.elastic.co/guide/en/elasticsearch/client/php-api/master/_overview.html). I'm not up-to-speed on how the asciidoc are generated for this client, but can we consider explicitly adding IDs (e.g. [[overview]]) in the files?

[nik9000]

can we consider explicitly adding IDs (e.g. [[overview]]) in the files?

I think that'd be a good idea, yeah. I'm fairly sure we didn't end up changing any of the urls when we switched to Asciidoctor, just the IDs on the page, luckily.

[nik9000]

@polyfractal an important thing: you'll need to use ./build_docs --asciidoctor when you build the book locally from here on out. This change updates the bash aliases file in the docs repo to tell you that, but I figure it is worth calling out specifically.

[polyfractal]

Noted, thanks for the headsup!

And having explicit IDs for pages seems like a good idea to me too.

[lcawl]

Cool, I'll do a quick PR before I forget. Perhaps we can add redirects via your new process too, @nik9000

[nik9000]

Perhaps we can add redirects via your new process too, @nik9000

I've merged the file with the redirects in it but no one has picked it up yet. And I haven't built the spiffy "easy mode" redirects yet at all. But I expect we'll be able to stuff the new redirects into the docs repo sometime next week and be pretty confident about them.