Introduce cross-cluster replication API docs

[jasontedor]

This commit is our first introduction to cross-cluster replication docs. In this commit, we introduce the cross-cluster replication API docs. We also add skelton docs for additional content that will be added in a series of follow-up commits.

[elasticmachine]

Pinging @elastic/es-distributed

[jasontedor]

This PR is the first in a series of PRs that will introduce docs for CCR. We breakdown the introduction of these docs into a series of PRs to ease reviewing. I am aware that there is work outstanding that will render some of these docs broken (that is, we are actively making breaking API changes). I want that work to go in first, and then I will keep this PR up-to-date with those changes. However, I want reviewing to get started, and I want to start opening up the follow-up PRs.

[jasontedor]

For reviewers not use to the workflow of working with the docs, here is the simplest way to read these docs:

$ git clone -o elastic [email protected]:elastic/docs.git && \
export GIT_HOME=. && \
source docs/doc_build_aliases.sh; \
git clone -o elastic [email protected]:elastic/elasticsearch.git && \
git -C elasticsearch remote add jasontedor [email protected]:jasontedor/elasticsearch.git && \
git -C elasticsearch fetch jasontedor ccr-docs && \
git -C elasticsearch checkout ccr-docs && \
docbldesx

Then you can open the resulting index HTML page, navigate to X-Pack APIs, and then navigate to cross-cluster replication (e.g., on macOS you could do open html_docs/index.html).

If you already have the elastic/docs and elastic/elasticsearch repositories cloned to the same parent directory, you can set GIT_HOME to that parent directory. Note that you will still need to add my remote.

[jasontedor]

This is removed because it is now used in the setup section of some of the docs tests, and setup sections do not support is_true sections. While we could add support for is_true sections to setup section, this assertion is adding little value to begin with.

[lcawl]

@jasontedor I took a quick look and one thing I don't see in the APIs is an "Authorization" section, which lists what roles or privileges are required to run the API when security is enabled. Is this something you plan to add?

I noticed a few other sections missing, so I'll submit suggestions for your perusal.

[lcawl]

Suggested change

	Here, `<follower_index>` is the name of the follower index to pause.
	==== Path Parameters
	`follower_id` (required)::
	(string) Identifier for the follower index.

[lcawl]

Suggested change

	==== Path Parameters
	`auto_follow_pattern_name` (required)::
	(string) Specifies auto-follow patterns that you want to delete.

[lcawl]

Suggested change

	==== Path Parameters
	`auto_follow_pattern_name` ::
	(string) Specifies the auto-follow patterns that you want to retrieve. If you do not specify any patterns, the API returns information for all patterns.

[lcawl]

Suggested change

	==== Path Parameters
	`auto_follow_pattern_name` (required)::
	(string) Identifier for the auto-follow patterns.

[lcawl]

Are there rules for what this name can contain? For example, for job names, we say "This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters."

[lcawl]

Suggested change

	`leader_cluster`::
	`leader_cluster` (required) ::

[lcawl]

Suggested change

	(required string) the <<modules-remote-clusters,remote cluster>> containing the
	(string) The <<modules-remote-clusters,remote cluster>> containing the

[lcawl]

Suggested change

	(array) an array of simple index patterns to match against indices in the
	(array) An array of simple index patterns to match against indices in the

[lcawl]

Suggested change

	(string) the name of follower index; the template `{{leader_index}}` can be
	(string) The name of follower index; the template `{{leader_index}}` can be

[lcawl]

Suggested change

	(integer) the maximum number of operations to pull per fetch from the remote
	(integer) The maximum number of operations to pull per fetch from the remote

[lcawl]

Suggested change

	(long) the maximum number of concurrent fetches from the remote cluster
	(long) The maximum number of concurrent fetches from the remote cluster

[lcawl]

Suggested change

	(<<byte-units,byte value>>) the maximum size in bytes of batches pulled per
	(<<byte-units,byte value>>) The maximum size in bytes of batches pulled per

[lcawl]

Suggested change

	The following is an example of using the pause follower API.
	This example pauses a follower index named `follower_index`:

[lcawl]

Suggested change

	The following is an example of using the resume follower API.
	This example resumes a follower index named `follower_index`:

[lcawl]

Suggested change

	The following is an example of using the unfollow API.
	This example converts `follower_index` from a follower index to a regular index:

[lcawl]

Suggested change

	The following is an example of using the create follower API.
	This example creates a follower index named `follower_index`:

[nik9000]

I looked at the snippets and have two comments:

1. You have a bunch of empty // TEST comments. // CONSOLE implies // TEST so you shouldn't need them but they don't hurt anything. // TEST exists primarily to send extra stuff to the test framework rather than the doc generation framework.
2. In a few places you clean up after a test using // TEST[continued]. I think the // TEARDOWN annotation that you built is better for that. But, I wonder if these are things that should be cleaned up higher up, like we do with rollups and such. I'm don't think the answer to that question should block merging, but it is a thing to think about.

[jasontedor]

Thanks @lcawl, I've incorporated your feedback.