Convert docs from markdown to asciidoc #92

[pyokagan]

Fixes #92

Convert our documentation from markdown to asciidoc format, in order to
take advantage of the additional features and semantic elements that
asciidoc offers such as automatic section numbering, admonitions and
automatic table of contents (TOC) generation.

Implement a simple build+deployment system to automatically publish our
documentation to https://oss-generic.github.io/process/

---

The result (based on the tip of this PR) can be seen at https://pyokagan.github.io/oss-generic-process/ Please help to proof-read it! (Might make for some nice bedtime reading)

Note that the main goal of the PR is to convert the bulk documentation to asciidoc, so I'd rather not spend too much time on the build system aspect of this PR (e.g. using a full-featured static website generator or more advanced templating etc.) More advanced enhancements can be done later by someone else.

[damithc]

Nice. Let me know when you expect some input from me.

[CanIHasReview-bot]

v1

@pyokagan submitted v1 for review.

• [v1 1/15] Translate markdown files into asciidoc files
• [v1 2/15] Setup asciidoc-to-html build system
• [v1 3/15] build system: handle README.adoc as an index page
• [v1 4/15] build system: implement `npm run watch`
• [v1 5/15] Use automatic TOC generation
• [v1 6/15] Use inter-document cross-references
• [v1 7/15] Replace deep list nesting with subsections
• [v1 8/15] Restore HTML content erased by pandoc
• [v1 9/15] Fix "section title out of sequence" warnings
• [v1 10/15] No explicit numbering of numbered list items
• [v1 11/15] Use admonition/sidebar blocks instead of quote blocks
• [v1 12/15] Remove unnecessary link anchors
• [v1 13/15] Fix rendering errors
• [v1 14/15] Remove markdown files
• [v1 15/15] TO REMOVE BEFORE MERGE

(:books: Archive)

Checkout this PR version locally

```sh git fetch https://github.com/oss-generic/process.git refs/pr/93/1/head:BRANCHNAME ``` where `BRANCHNAME` is the name of the local branch you wish to fetch this PR to.

[pyokagan]

+cc documentation authors @Skaty @li-kai @AngShiYa @chao1995 @yamgent @acjh

[damithc]

I forgot to add: Some of the the // TODO fillers in the previous version seem to have disappeared, resulting in section titles without any body.

[pyokagan]

@damithc

Some of the the // TODO fillers in the previous version seem to have disappeared, resulting in section titles without any body.

OK.

[CanIHasReview-bot]

v2

@pyokagan submitted v2 for review.

• [v2 1/17] Translate markdown files into asciidoc files
• [v2 2/17] Setup asciidoc-to-html build system
• [v2 3/17] build system: handle README.adoc as an index page
• [v2 4/17] Use automatic TOC generation
• [v2 5/17] Use inter-document cross-references
• [v2 6/17] Replace deep list nesting with subsections
• [v2 7/17] Restore HTML content erased by pandoc
• [v2 8/17] Fix "section title out of sequence" warnings
• [v2 9/17] Remove explicit numbering of numbered list items
• [v2 10/17] Use admonition/sidebar blocks instead of quote blocks
• [v2 11/17] Remove unnecessary link anchors
• [v2 12/17] Ensure asciidoctor renders certain lines starting with `//`
• [v2 13/17] Fix rendering errors in all adoc documents
• [v2 14/17] Remove markdown files
• [v2 15/17] AdvancedContributorGuidelines: remove "Updating a PR in response to a review"
• [v2 16/17] CodingStandard-Java.adoc: introduce and use {star} substitution
• [v2 17/17] TO REMOVE BEFORE MERGE

(:books: Archive) (:chart_with_upwards_trend: Interdiff between v1 and v2)

Checkout this PR version locally

```sh git fetch https://github.com/oss-generic/process.git refs/pr/93/2/head:BRANCHNAME ``` where `BRANCHNAME` is the name of the local branch you wish to fetch this PR to.

[pyokagan]

v2

• Simplified build.js script.
• Rebased on master, including the massive changes in the Java coding standard. (I actually redid all the commits, but with an updated pandoc version which generated slightly different asciidoc output, which is why there are random changes in the interdiff).

TIL: :trollface: isn't an actual unicode emoji :trollface: I used an image instead.

[pyokagan]

@damithc Done. You'll need to set up Travis CI on this repo with the GITHUB_TOKEN environment variable set to a personal access token of an account which can push to this repo. The usual stuff :-)