Painless Spec Documentation Clean Up #29441

jdconrad · 2018-04-10T03:53:36Z

First sweep of Painless spec documentation clean up. The following changes have been made:

Restructure the Painless spec sections for basic syntax.
Clean up the documentation sections Comments, Keywords, and Literals.
Clean up the examples for the sections Comments, Keywords, and Literals.
Clean up the introduction to the Painless Spec.
Add a table of contents following the introduction of the Painless Spec.
Clean up the Painless Reference API introduction.
Create consistent ids for the different headers in the spec.

elasticmachine · 2018-04-10T03:53:37Z

Pinging @elastic/es-core-infra

nik9000 · 2018-04-10T14:58:23Z

docs/painless/index.asciidoc

@@ -5,39 +5,8 @@ include::../Versions.asciidoc[]

 include::painless-getting-started.asciidoc[]


I think it'd be nice to fix up painless-description at some point. It talks about "alternatives" like groovy is still an alternative.

And it'd be good to clean up getting-started at some point too. Both are fine to do later.

Agreed on both. Most of the documentation needs some editing. Definitely different PRs.

nik9000 · 2018-04-10T15:04:24Z

docs/painless/painless-basic-syntax.asciidoc

+*Grammar:*
+[source,ANTLR4]
+----
+SINGLE_LINE_COMMENT: '//' .*? [\n\r];


If you are really into including bits of the grammar you can actually include it at documentation build time with a construct like this one:

["source","ANTLR4",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{parser}[comments] --------------------------------------------------

It'd be a neat thing to do in a followup because it'd make sure the grammar never goes out of date.

I will keep this in mind. Some of the grammar has been modified for the documentation and does not directly follow the current grammar precisely out of convenience for the reader.

nik9000 · 2018-04-10T15:09:15Z

docs/painless/painless-basic-syntax.asciidoc

+----
+// single-line comment
+
+<code> // single-line comment


I'd probably write some actual code here, like int i = 0; // single line comment or something.

nik9000 · 2018-04-10T15:11:14Z

docs/painless/painless-basic-syntax.asciidoc

+Integer literals of `int 0`, `double 0.0`, `long 1234`,
+`float -90.0`, `int -18` in octal, and `int 3882` in hex.
+
+[source,Java]


I'd probably use [source,painless] here instead. The language doesn't really do anything at documentation rendering time. It is used more when we test the documentation. And it might be useful to have this be accurate.

Done. Will work through switching all the examples as I edit those sections.

nik9000 · 2018-04-10T15:13:27Z

docs/painless/painless-basic-syntax.asciidoc

+*Examples:*
+[source,Java]
+----
+_


I wonder if we should document that _ is a valid variable identifier. I think Java has been trying to move away from that.

Removed from the docs. Probably not worth removing from the language at this point given backwords compat issues, but that's a different discussion.

nik9000 · 2018-04-10T15:17:40Z

docs/painless/painless-basic-syntax.asciidoc

+
+*Examples:*
+
+Assigning a literal of the appropriate type directly to a declared variable.


I'd probably replace the trailing . with a : because it is describing the block. I'm not sure what feels more right to be honest.

I'm going to stick with standard sentence notation as it's more natural if there's more than one sentence.

As long as it's consistent, either (or even none) works. I'd be inclined to drop the colons after the Grammar and Examples headings, they aren't really necessary.

Will remove the colons from example and grammar as I work through editing the sections.

nik9000 · 2018-04-10T15:18:14Z

docs/painless/painless-basic-syntax.asciidoc

+
+[source,Java]
+----
+ArrayList l = new ArrayList();  // Declare an ArrayList variable l and set it


This one is one character too wide on my screen. The t gets cut off.

Didn't get to that section yet. Only edited comments, keywords, and literals so far.

rjernst

LGTM, I left a few thoughts.

rjernst · 2018-04-10T15:38:31Z

docs/painless/painless-api-reference.asciidoc

+Elasticsearch or Painless itself. Below is a list of all available
+classes grouped with their respected methods. Clicking on the method
+name takes you to the documentation for that specific method.  Methods
+defined in the JRE also have a `(java 9)` link which can be used to see


We should consider (not here, but as a followup/separate issue) changing this to java 10, since in 6.3 we are changing to java 10 support.

I agree, this whole thing needs to be updated, and it's actually blocking finishing up type removal. Just never had the opportunity to go back and modify it for contexts as well.

I'd mention the Java version once and avoid repeating it in every link.

Well the links redirect to the Java 9 counterpart, but I agree that we need a better overall solution to keep up with the Java API moving forward. I might be inclined to only link to the last long-term release, but I'm not sure that's correct depending on what version we are technically supporting for each ES release.

rjernst · 2018-04-10T15:44:15Z

docs/painless/painless-basic-syntax.asciidoc

+===== Floats
+
+Use floating point literals to specify a floating point value of the
+<<primitive-types, primitive types>> float or double. Use the following single


Should float and double be in a monospace font (as they are below)?

jdconrad · 2018-04-11T20:22:46Z

@debadair Do you have a bit of time to review this soon? If not, are you okay with me going with the current feedback and maybe you could come back around to more editing in the future? Thanks in advance.

debadair

Added some general comments. After this is merged, I can do an editing pass and open a PR.

debadair · 2018-04-12T18:18:51Z

docs/painless/painless-api-reference.asciidoc

@@ -1,17 +1,14 @@
-["appendix",id="painless-api-reference"]
+[appendix]
+[[painless-api-reference]]


I wouldn't make this an appendix, it's fine as a regular top-level section.

Will remove. Was just leaving it as it was. What's the purpose of appendix in this case, does it add anything special to the docs other than the 'A'?

debadair · 2018-04-12T18:25:20Z

docs/painless/index.asciidoc

 include::painless-lang-spec.asciidoc[]

-include::painless-syntax.asciidoc[]
+include::painless-general-syntax.asciidoc[]



I'd include this from painless-lang-spec.asciidoc, rather than at the top level so it reflects how things are actually nested.

Changed, please note this is how it was before.

debadair · 2018-04-12T18:29:14Z

docs/painless/painless-lang-spec.asciidoc

@@ -1,73 +1,46 @@
-[[painless-specification]]
+[[painless-lang-spec]]
 == Painless Language Specification


Changing the anchor text changes the name of the generated page. That's fine, but we need to keep track of the changes so we can have the webteam set up redirects.

This is unfortunate, but I think the changes to the documentation structure are important for our users in this case.

debadair · 2018-04-12T19:43:04Z

docs/painless/painless-literals.asciidoc

@@ -1,94 +0,0 @@
-[[literals]]
-=== Literals


Moving these sections under Basic syntax also means we need a redirect, because they are no longer separate pages.

Rather than combining this into the other file, I probably would have kept it separate and included it.

Separated all the sections out to separate pages after our conversation. Hopefully, this is easier to work with and better for the user.

debadair · 2018-04-12T19:54:44Z

docs/painless/painless-lang-spec.asciidoc

+** <<promotion, Promotion>>
+* <<painless-operators, Operators>>
+* <<painless-general-syntax, General Syntax>>
+


I think we'd be better off with a single syntax section. The "Basic" and "General" groupings aren't really going to help people know where to look.

debadair · 2018-04-12T20:25:39Z

docs/painless/painless-basic-syntax.asciidoc

+*Examples:*
+
+String literals using both single-quotes and double-quotes.
+


I'd probably split this into "Single quoted string literals" and "Double quoted string literals" examples.

debadair · 2018-04-12T20:28:54Z

docs/painless/painless-basic-syntax.asciidoc

+*Examples:*
+
+Floating point literals of `double 0.0`, `double 1000000.0` in
+exponent notation, `double 0.977777`, `double -126.34`, and `float 89.9`.


Maybe use comments like you did in the variable declaration section?

Switched to callouts.

debadair · 2018-04-12T20:31:43Z

docs/painless/painless-basic-syntax.asciidoc

+[source,Java]
+----
+int i = 10;     // Declare the int variable i and set it the int literal 1
+double j = 2.0; // Declare the double variable j and set it to the double


Should be 10?

Haven't updated this section yet. Will do so in another PR.

debadair · 2018-04-12T20:34:41Z

docs/painless/painless-basic-syntax.asciidoc

+                          //    default value null
+m = k;                    // Set the value of List variable m to the value
+                          //    of List variable k
+----


Inserting a blank line before each example would make it a little easier to read the wrapped comments. We could use callouts instead of the comments, but I think there are advantages to keeping the info inline.

Started to switch some to callouts. I really like the formatting of the callouts and think that can make it easier to follow the examples.

debadair · 2018-04-12T20:35:14Z

docs/painless/painless-lang-spec.asciidoc

-
-<code> // single-line comment
+This specification is divided into the following sections:
+


The intro text isn't really necessary.

Removed this and with the flatten structure removed the links as well as they show up in the sidebar.

jdconrad · 2018-04-16T19:15:03Z

@debadair Hey Deb, as per our conversation, I've updated the painless spec into a flatter structure and separate pages. Also tried to do more clean up on the 3 sections comments, keywords, and literals. Once this PR is completed, I'll move onto the next section. Thanks for all the help so far!

debadair · 2018-04-17T18:35:12Z

Just built it & I think the flatter structure works better. I think the callouts and other changes make to those sections make it easier to read the examples.

LGTM!

jdconrad · 2018-04-17T19:16:41Z

@debadair @rjernst @nik9000 Thanks for the reviews!

* master: Remove the index thread pool (#29556) Remove extra copy in ScriptDocValues.Strings Fix full cluster restart test recovery (#29545) Fix binary doc values fetching in _search (#29567) Mutes failing MovAvgIT tests Fix the assertion message for an incorrect current version. (#29572) Fix the version ID for v5.6.10. (#29570) Painless Spec Documentation Clean Up (#29441) Add versions 5.6.10 and 6.2.5 [TEST] test against scaled value instead of fixed epsilon in MovAvgIT Remove `flatSettings` support from request classes (#29560) MapperService to wrap a single DocumentMapper. (#29511) Fix dependency checks on libs when generating Eclipse configuration. (#29550) Add null_value support to geo_point type (#29451) Add documentation about the include_type_name option. (#29555) Enforce translog access via engine (#29542)

Created a flatter structure for the different sections. Cleaned up comments, keywords, and literals. Used callouts for examples where it made sense.

jdconrad added 6 commits April 5, 2018 10:01

Start of updating existing docs.

89c21ba

More docs changes.

3767359

More doc changes.

60839d7

Merge branch 'master' into docs0

04b59dc

More doc changes.

dc1d032

More docs.

2eef33e

jdconrad added >docs General docs changes :Core/Infra/Scripting Scripting abstractions, Painless, and Mustache v7.0.0 v6.3.0 labels Apr 10, 2018

jdconrad requested review from rjernst and debadair April 10, 2018 03:53

nik9000 reviewed Apr 10, 2018

View reviewed changes

jdconrad mentioned this pull request Apr 10, 2018

Painless: Improve Documentation #23777

Closed

22 tasks

rjernst approved these changes Apr 10, 2018

View reviewed changes

debadair reviewed Apr 12, 2018

View reviewed changes

jdconrad added 4 commits April 13, 2018 09:34

Merge branch 'master' into docs0

6d21cd3

More docs.

bb3080a

Merge branch 'master' into docs0

98a9c94

More doc updates.

e93728d

jdconrad merged commit c833167 into elastic:master Apr 17, 2018

jdconrad added the backport pending label Apr 17, 2018

jdconrad added a commit that referenced this pull request Apr 18, 2018

Painless Spec Documentation Clean Up (#29441)

4ceb102

Created a flatter structure for the different sections. Cleaned up comments, keywords, and literals. Used callouts for examples where it made sense.

jdconrad removed the backport pending label Apr 18, 2018

jdconrad deleted the docs0 branch June 8, 2018 00:38

colings86 added v7.0.0-beta1 and removed v7.0.0 labels Feb 7, 2019

		@@ -5,39 +5,8 @@ include::../Versions.asciidoc[]

		include::painless-getting-started.asciidoc[]


		Examples:

		Assigning a literal of the appropriate type directly to a declared variable.

		Examples:

		String literals using both single-quotes and double-quotes.


		<code> // single-line comment
		This specification is divided into the following sections:

Painless Spec Documentation Clean Up #29441

Painless Spec Documentation Clean Up #29441

Conversation

jdconrad commented Apr 10, 2018

elasticmachine commented Apr 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdconrad Apr 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rjernst left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdconrad commented Apr 11, 2018

debadair left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdconrad commented Apr 16, 2018

debadair commented Apr 17, 2018

jdconrad commented Apr 17, 2018

jdconrad Apr 12, 2018 •

edited

Loading