[DOCS] Add XPack Reporting to Kibana Guide by lcawl · Pull Request #12062 · elastic/kibana

lcawl · 2017-05-29T22:59:50Z

This PR adds X-Pack information about the "Reporting" feature to the Kibana Reference.

It also adds some attributes and comments that will be used by other future additions.

epixa · 2017-05-30T00:16:14Z

I get this error when I try to build the Kibana docs when I don't have x-pack-kibana cloned next to Kibana:

courtmbp:docs Court$ ./build_docs.pl --doc ../kibana/docs/index.asciidoc --chunk=1 --open
Building HTML from ../kibana/docs/index.asciidoc

asciidoc: WARNING: index.asciidoc: line 60: include file not found: /p/kibana/docs/../../x-pack-kibana/docs/en/reporting/index.asciidoc

epixa · 2017-05-30T00:20:57Z

Is there a reason this is targeting 5.x instead of master? Generally we issue pull requests against master and then backport them to the appropriate branches, even for doc changes

lcawl · 2017-05-30T00:57:24Z

@epixa This integration is targeted for 5.x, so I started there. You're right that it will be pushed to master too though.

Please note I've added a new commit that includes new index-all.asciidoc and index-shared.asciidoc files. In my initial tests, this means external users can keep using index.asciidoc, which only has access to open repositories.

epixa · 2017-05-30T13:41:00Z

docs/index.asciidoc

The index-shared.asciidoc file was not added to this PR, so I don't think this will build.

oops, I've added those new files now

epixa · 2017-05-30T13:41:43Z

docs/index.asciidoc

I can't tell for sure without seeing index-shared, but perhaps this variable name could be a bit more descriptive? Maybe something like repo-state?

@clintongormley suggested include-xpack, so I'll go with that.

epixa · 2017-05-30T15:46:44Z

docs/index-shared.asciidoc

Can you preserve the original comment above this to indicate the different possibilities for release-state?

////////// release-state can be: released | prerelease | unreleased //////////

epixa · 2017-05-30T15:48:47Z

docs/index-shared.asciidoc

Can you increase the spacing between these variables and their contents so that they are all inline with each other? The spacing should always equal 2 spaces beyond the largest variable name.

epixa · 2017-05-30T15:51:26Z

docs/index-shared.asciidoc

Let's exclude the commented out sections that don't exist yet unless there is a specific reason to keep them in. We avoid merging commented out docs or code because it's not clear to future committers why those things are commented out.

clintongormley

LGTM, I've just added two comments

clintongormley · 2017-05-30T16:04:36Z

docs/index-shared.asciidoc

This can be defined regardless of the include-xpack setting

clintongormley · 2017-05-30T16:05:20Z

docs/index-shared.asciidoc

This can be shortened to:

{include-xpack#}include::{xkb-repo-dir}/reporting/index.asciidoc[]

When I tried that, it didn't include the content. Is it okay to leave the ifeval since that works?

clintongormley · 2017-05-31T11:23:41Z

docs/index-shared.asciidoc

Sorry, as you point out this syntax doesn't work for includes:

{include-xpack#}include::....

However this syntax does:

ifdef::include-xpack[] include::{xkb-repo-dir}/reporting/index.asciidoc[] endif::include-xpack[]

and it slightly lighter than ifeval

epixa · 2017-05-31T13:52:34Z

When I enable :include-xpack: with the latest 5.x of x-pack-kibana checked out as a sibling, building the docs fails with:

courtmbp:docs Court$ ./build_docs.pl --doc ../kibana/docs/index.asciidoc --chunk=1 --open
Building HTML from ../kibana/docs/index.asciidoc

Error executing: a2x -v --icons -d book -f chunked -a showcomments=1 -a lang=en -a base_edit_url= -a root_dir=/p/docs/../kibana/docs --xsl-file resources/website_chunked.xsl --asciidoc-opts -fresources/es-asciidoc.conf --destination-dir=/p/docs/html_docs --xsltproc-opts --stringparam toc.max.depth '5' --xsltproc-opts --stringparam toc.section.depth '1' --xsltproc-opts --stringparam chunk.section.depth '1' --xsltproc-opts --stringparam local.book.version 'test build' --xsltproc-opts --stringparam local.book.multi_version '0' --xsltproc-opts --stringparam local.page.header '' --xsltproc-opts --stringparam local.book.section.title 'Docs/' /p/docs/../kibana/docs/index.asciidoc 



/p/docs/html_docs/index.xml:10839: element link: validity error : IDREF attribute linkend references an unknown ID "configure-kibana-cert"
/p/docs/html_docs/index.xml:10782: element link: validity error : IDREF attribute linkend references an unknown ID "configuring-email"
/p/docs/html_docs/index.xml:10912: element link: validity error : IDREF attribute linkend references an unknown ID "configuring-email"
/p/docs/html_docs/index.xml:10639: element link: validity error : IDREF attribute linkend references an unknown ID "installing-xpack"
/p/docs/html_docs/index.xml:10807: element link: validity error : IDREF attribute linkend references an unknown ID "how-watcher-works"
/p/docs/html_docs/index.xml:10937: element link: validity error : IDREF attribute linkend references an unknown ID "how-watcher-works"
/p/docs/html_docs/index.xml:10744: element link: validity error : IDREF attribute linkend references an unknown ID "configuring-email-actions"
/p/docs/html_docs/index.xml:10833: element link: validity error : IDREF attribute linkend references an unknown ID "security-getting-started"
/p/docs/html_docs/index.xml:10824: element link: validity error : IDREF attribute linkend references an unknown ID "reporting-settings"
/p/docs/html_docs/index.xml:10646: element link: validity error : IDREF attribute linkend references an unknown ID "secure-reporting"
/p/docs/html_docs/index.xml:10867: element link: validity error : IDREF attribute linkend references an unknown ID "secure-reporting"


---
a2x: ERROR: "xmllint" --nonet --noout --valid "/p/docs/html_docs/index.xml" returned non-zero exit status 4

epixa · 2017-05-31T13:55:20Z

I switched up my x-pack-kibana to the recent reporting PR you submitted there, and the error changes to:

courtmbp:docs Court$ ./build_docs.pl --doc ../kibana/docs/index.asciidoc --chunk=1 --open
Building HTML from ../kibana/docs/index.asciidoc

Error executing: a2x -v --icons -d book -f chunked -a showcomments=1 -a lang=en -a base_edit_url= -a root_dir=/p/docs/../kibana/docs --xsl-file resources/website_chunked.xsl --asciidoc-opts -fresources/es-asciidoc.conf --destination-dir=/p/docs/html_docs --xsltproc-opts --stringparam toc.max.depth '5' --xsltproc-opts --stringparam toc.section.depth '1' --xsltproc-opts --stringparam chunk.section.depth '1' --xsltproc-opts --stringparam local.book.version 'test build' --xsltproc-opts --stringparam local.book.multi_version '0' --xsltproc-opts --stringparam local.page.header '' --xsltproc-opts --stringparam local.book.section.title 'Docs/' /p/docs/../kibana/docs/index.asciidoc 

---
a2x: ERROR: missing resource: /p/kibana/docs/images/reporting.jpg

lcawl · 2017-05-31T15:31:36Z

@epixa I think you're missing the following parameter, which is required to find the images:
--resource=../x-pack-kibana/docs/
We included that detail in the readme for the X-Pack repo, but can include in the Kibana repo if appropriate too.

lcawl · 2017-05-31T15:43:07Z

@clintongormley I've switched to using ifdef (and removed the conditional clause around the xkb-repo-dir attribute) per your suggestions. Thanks!

epixa · 2017-05-31T16:03:11Z

Adding these docs as-is makes the Kibana docs pretty confusing. The Kibana docs never describe how to install x-pack, or even what X-Pack is, and then suddenly there's a section about an x-pack feature, and it's not clear how you get it.

The first reporting page you'll see is: xpack-reporting.html, which briefly breezes over what x-pack offers, but it doesn't explain anything about x-pack being a commercial product or that x-pack doesn't come with Kibana by default.

It was OK to breeze over this sort of thing in the dedicated x-pack documentation since we could assume a person already has learned about x-pack before going to the docs, but that isn't the case when someone is on the Kibana docs.

I could see a couple of ways of addressing this:

Draw a more clear separation between X-Pack features in the docs hierarchy, so we can have a "getting started with x-pack" section before any of the individual x-pack features.
Intersperse introductory x-pack documentation earlier in the docs, perhaps in the "set up kibana" section.

My preference is for 1, but I'm not sure to what level this stuff has already been discussed.

debadair · 2017-05-31T18:49:15Z

I actually have a fairly strong preference for the second option for a couple reasons:

We want to minimize the number of different places people have to go to piece together how to get things up and running.
When you install X-Pack, they appear just like other Kibana plugins in the UI. The docs should reflect that.

My recommendation would be to:

Add a blurb about X-Pack to the introduction that references the features that require X-Pack. (Maybe in terms of the Kibana platform is extensible, and X-Pack is an extension pack that adds a number of useful Elastic Stack features?)
Add a Installing X-Pack section at the end of the set up topic that shows the bin/kibana-plugin install x-pack command and links back to the X-Pack Installation.
Link back to the Installing X-Pack info from the topics for the X-Pack features.

lcawl · 2017-06-02T18:14:07Z

Thanks @debadair I've implemented your suggestions!

lcawl · 2017-06-15T19:05:26Z

This PR now contains the bare minimum changes required to address the issue (see issue link at beginning for bigger picture).

lcawl · 2017-06-20T20:14:51Z

The index has now been split into four parts to facilitate re-use elsewhere.

* [DOCS] Add XPack Reporting to Kibana Guide * [DOCS] Add attributes for private vs open repo builds * [DOCS] Add index-shared.asciidoc * [DOCS] Address feedback on index-shared.asciidoc * [DOCS] Add X-Pack introduction to Kibana Guide * [DOCS] Add X-Pack installion to Kibana Guide * [DOCS] Fix duplicate security attribute in index-shared.asciidoc * [DOCS] Further fix duplicate security attribute in index-shared.asciidoc * [DOCS] Revert changes to intro and setup * [DOCS] Split index-shared.asciidoc * [DOCS] Add index-shared5.asciidoc

lcawl added Team:Docs v5.5.0 labels May 29, 2017

lcawl requested a review from debadair May 29, 2017 22:59

epixa suggested changes May 30, 2017

View reviewed changes

clintongormley reviewed May 30, 2017

View reviewed changes

clintongormley reviewed May 31, 2017

View reviewed changes

spalger added the v5.6.0 label Jun 7, 2017

lcawl mentioned this pull request Jun 9, 2017

[DOC] Add X-Pack links to Elasticsearch Reference elastic/elasticsearch#25164

Merged

lcawl added the v6.0.0 label Jun 9, 2017

lcawl mentioned this pull request Jun 13, 2017

[DOCS] Add references to X-Pack installation and overview elastic/elasticsearch#25188

Closed

lcawl force-pushed the lcawley-reporting branch from 3be96c4 to 4a1d611 Compare June 15, 2017 18:12

lcawl force-pushed the lcawley-reporting branch from 75a98f4 to 724d7f6 Compare June 20, 2017 15:28

lcawl added 5 commits June 21, 2017 16:26

[DOCS] Add XPack Reporting to Kibana Guide

3944ac1

[DOCS] Add attributes for private vs open repo builds

b6cbd8e

[DOCS] Add index-shared.asciidoc

c38f0e6

[DOCS] Address feedback on index-shared.asciidoc

de6b4e2

[DOCS] Add X-Pack introduction to Kibana Guide

fd9d15d

lcawl added 6 commits June 21, 2017 16:27

[DOCS] Add X-Pack installion to Kibana Guide

f7097dd

[DOCS] Fix duplicate security attribute in index-shared.asciidoc

27382ce

[DOCS] Further fix duplicate security attribute in index-shared.asciidoc

091c076

[DOCS] Revert changes to intro and setup

83f87b8

[DOCS] Split index-shared.asciidoc

8024d39

[DOCS] Add index-shared5.asciidoc

c8e9310

lcawl force-pushed the lcawley-reporting branch from 277602d to c8e9310 Compare June 21, 2017 23:29

lcawl merged commit bc3f3fa into elastic:5.x Jun 21, 2017

lcawl deleted the lcawley-reporting branch June 21, 2017 23:30

lcawl mentioned this pull request Jun 22, 2017

[DOCS] Update paths for Kibana Guide in conf.yaml elastic/docs#201

Merged

Conversation

lcawl commented May 29, 2017

Uh oh!

epixa commented May 30, 2017

Uh oh!

epixa commented May 30, 2017

Uh oh!

lcawl commented May 30, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clintongormley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epixa commented May 31, 2017

Uh oh!

epixa commented May 31, 2017

Uh oh!

lcawl commented May 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lcawl commented May 31, 2017

Uh oh!

epixa commented May 31, 2017

Uh oh!

debadair commented May 31, 2017

Uh oh!

lcawl commented Jun 2, 2017

Uh oh!

lcawl commented Jun 15, 2017

Uh oh!

lcawl commented Jun 20, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lcawl commented May 31, 2017 •

edited

Loading