Painless: Improve Documentation

[jdconrad]

Painless documentation plan --

Quick Start - Use existing documentation to create quick start guide
Lang Spec - General lang spec for Painless
Examples - Show code for Painless
Bindings - Explain each available variable for the binding (context)

• Quick Start: Guide
• Lang Spec: Intro (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Comments (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Keywords (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Literals (Painless Spec Documentation Clean Up #29441)
• Lang Spec: Identifiers (Painless: Docs Clean Up #29592)
• Lang Spec: Variables (Painless: Docs Clean Up #29592)
• Lang Spec: Types (Painless: Types Section Clean Up #30283)
• Lang Spec: Casting (Painless: Types Section Clean Up #30283)
• Lang Spec: Operators (Painless: Restructure Spec Documentation #31013)
• Lang Spec: Statements
• Lang Spec: Scripts
• Lang Spec: Functions
• Lang Spec: Lambdas
• Lang Spec: Regex
• Examples: General
• Examples: Dates
• Contexts: API (Painless: Add Context Docs #31190)
• Contexts: Fields
• Contexts: Examples (in progress) (Painless: Add an Ingest Script Processor Example #32302) (Painless: Add reindex docs example #34024) ([Painless] Context Doc Examples #34829) (jdconrad)
• Other: Debugging
• Other: Execution

[jdconrad]

Wanted to give an update on this: @debadair has done some significant editing on the intro and constants, variables, and types sections. And she's come up with this as a possible model for the re-vamped documentation moving forward:

    Painless Scripting

    <introduction>

        Getting Started with Painless

            Accessing Doc Values 

            Updating Fields

            Working with Dates

            Using Regular Expressions

            Debugging Painless Scripts

    Example Scripts

        Using Painless in Script Fields

        Using Painless in Watches

        Using Painless in Function Score Queries

        Using Painless in Script Queries

        Using Painless When Updating Docs

        Using Painless When Reindexing

    How Painless Works

        Painless Architecture

        Dispatching Functions

    Painless Language Specification

    Painless API Reference

I am about 3/4 of the way through the operators section and plan to be done this week after which I'll hand it off for editing and move onto Control Flow.

I'm thinking that we an edit what already exists into the quick start guide and possibly post the lang spec with the initial 5 sections -- intro, constants variables and types, operators, control flow, and structure. This will help get some better docs out sooner, and then move forward from there.

[jdconrad]

Added the working progress to a branch here: https://github.com/jdconrad/elasticsearch/blob/painless-docs/docs/reference/modules/scripting/painless-lang-spec.asciidoc\

Important: This does not contain the editing that Deb has done yet! It's very raw still.

[clintongormley]

See https://www.elastic.co/guide/en/elasticsearch/painless/current/index.html for this work in progress

[jdconrad]

Update: No real progress as script contexts have taken priority. @talevy has kindly volunteered to help with some of the script context example documentation when he has a bit of time.