docs: kibana developer and known plugin docs (#9477)

* docs: kibana developer docs

This is the beginning of developer-focussed docs for Kibana. The content
is mostly pulled directly from the old wiki in the github repo.

* docs: known plugins for 5.x

docs/development.asciidoc

@@ -0,0 +1,16 @@
+[[development]]
+= Contributing to Kibana
+
+[partintro]
+--
+Contributing to Kibana can be daunting at first, but it doesn't have to be. If
+you're planning a pull request to the Kibana repository, you may want to start
+with <<core-development>>.
+
+If you'd prefer to use Kibana's internal plugin API, then check out
+<<plugin-development>>.
+--
+
+include::development/core-development.asciidoc[]
+
+include::development/plugin-development.asciidoc[]

docs/development/core-development.asciidoc

@@ -0,0 +1,12 @@
+[[core-development]]
+== Core Development
+
+* <<development-basepath>>
+* <<development-dependencies>>
+* <<development-modules>>
+
+include::core/development-basepath.asciidoc[]
+
+include::core/development-dependencies.asciidoc[]
+
+include::core/development-modules.asciidoc[]

docs/development/core/development-basepath.asciidoc

@@ -0,0 +1,87 @@
+[[development-basepath]]
+=== Considerations for basePath
+
+All communication from the Kibana UI to the server needs to respect the
+`server.basePath`. Here are the "blessed" strategies for dealing with this
+based on the context:
+
+[float]
+==== `<img>` and `<a>` elements
+
+Write the `src` or `href` urls as you would without the base path, but then
+replace `src` or `href` with `kbn-src` or `kbn-href`.
+
+["source","shell"]
+-----------
+<img kbn-src="plugins/kibana/images/logo.png">
+-----------
+
+[float]
+==== Getting a static asset url
+
+Use webpack to import the asset into the build. This will give you a URL in
+JavaScript and gives webpack a chance to perform optimizations and
+cache-busting.
+
+["source","shell"]
+-----------
+// in plugin/public/main.js
+import uiChrome from 'ui/chrome';
+import logoUrl from 'plugins/facechimp/assets/banner.png';
+
+uiChrome.setBrand({
+  logo: `url(${logoUrl}) center no-repeat`
+});
+-----------
+
+[float]
+==== API requests from the front-end
+
+Use `chrome.addBasePath()` to append the basePath to the front of the url.
+
+["source","shell"]
+-----------
+import chrome from 'ui/chrome';
+$http.get(chrome.addBasePath('/api/plugin/things'));
+-----------
+
+[float]
+==== Server side
+
+Append `config.get('server.basePath')` to any absolute URL path.
+
+["source","shell"]
+-----------
+const basePath = server.config().get('server.basePath');
+server.route({
+  path: '/redirect',
+  handler(req, reply) {
+    reply.redirect(`${basePath}/otherLocation`);
+  }
+});
+-----------
+
+[float]
+==== BasePathProxy in dev mode
+
+The Kibana dev server automatically runs behind a proxy with a random
+`server.basePath`. This way developers will be constantly verifying that their
+code works with basePath, while they write it.
+
+To accomplish this the `serve` task does a few things:
+
+1. change the port for the server to the `dev.basePathProxyTarget` setting (default `5603`)
+2. start a `BasePathProxy` at `server.port`
+  - picks a random 3-letter value for `randomBasePath`
+  - redirects from `/` to `/{randomBasePath}`
+  - redirects from `/{any}/app/{appName}` to `/{randomBasePath}/app/{appName}` so that refreshes should work
+  - proxies all requests starting with `/{randomBasePath}/` to the Kibana server
+
+This proxy can sometimes have unintended side effects in development, so when
+needed you can opt out by passing the `--no-base-path` flag to the `serve` task
+or `npm start`.
+
+["source","shell"]
+-----------
+npm start -- --no-base-path
+-----------

docs/development/core/development-dependencies.asciidoc

@@ -0,0 +1,103 @@
+[[development-dependencies]]
+=== Managing Dependencies
+
+While developing plugins for use in the Kibana front-end environment you will
+probably want to include a library or two (at least). While that should be
+simple to do 90% of the time, there are always outliers, and some of those
+outliers are very popular projects.
+
+Before you can use an external library with Kibana you have to install it. You
+do that using...
+
+[float]
+==== npm (preferred method)
+
+Once you've http://npmsearch.com[found] a dependency you want to add, you can
+install it like so:
+
+["source","shell"]
+-----------
+npm install --save some-neat-library
+-----------
+
+At the top of a javascript file, just import the library using it's name:
+
+["source","shell"]
+-----------
+import someNeatLibrary from 'some-neat-library';
+-----------
+
+Just like working in node.js, front-end code can require node modules installed
+by npm without any additional configuration.
+
+[float]
+==== webpackShims
+
+When a library you want to use does use es6 or common.js modules but is not
+available on npm, you can copy the source of the library into a webpackShim.
+
+["source","shell"]
+-----------
+# create a directory for our new library to live
+mkdir -p webpackShims/some-neat-library
+# download the library you want to use into that directory
+curl https://cdnjs.com/some-neat-library/library.js > webpackShims/some-neat-library/index.js
+-----------
+
+Then include the library in your JavaScript code as you normally would:
+
+["source","shell"]
+-----------
+import someNeatLibrary from 'some-neat-library';
+-----------
+
+[float]
+==== Shimming third party code
+
+Some JavaScript libraries do not declare their dependencies in a way that tools
+like webpack can understand. It is also often the case that libraries do not
+`export` their provided values, but simply write them to a global variable name
+(or something to that effect).
+
+When pulling code like this into Kibana we need to write "shims" that will
+adapt the third party code to work with our application, other libraries, and
+module system. To do this we can utilize the `webpackShims` directory.
+
+The easiest way to explain how to write a shim is to show you some. Here is our
+webpack shim for jQuery:
+
+["source","shell"]
+-----------
+// webpackShims/jquery.js
+
+module.exports = window.jQuery = window.$ = require('node_modules/jquery/dist/jquery');
+require('ui/jquery/findTestSubject')(window.$);
+-----------
+
+This shim is loaded up anytime an `import 'jquery';` statement is found by
+webpack, because of the way that `webpackShims` behaves like `node_modules`.
+When that happens, the shim does two things:
+
+. Assign the exported value of the actual jQuery module to the window at `$` and `jQuery`, allowing libraries like angular to detect that jQuery is available, and use it as the module's export value.
+. Finally, a jQuery plugin that we wrote is included so that every time a file imports jQuery it will get both jQuery and the `$.findTestSubject` helper function.
+
+Here is what our webpack shim for angular looks like:
+
+["source","shell"]
+-----------
+// webpackShims/angular.js
+
+require('jquery');
+require('node_modules/angular/angular');
+require('node_modules/angular-elastic/elastic');
+require('ui/modules').get('kibana', ['monospaced.elastic']);
+module.exports = window.angular;
+-----------
+
+What this shim does is fairly simple if you go line by line:
+
+. makes sure that jQuery is loaded before angular (which actually runs the shim above)
+. load the angular.js file from the npm installation
+. load the angular-elastic plugin, a plugin we want to always be included whenever we import angular
+. use the `ui/modules` module to add the module exported by angular-elastic as a dependency to the `kibana` angular module
+. finally, export the window.angular variable. This means that writing `import angular from 'angular';` will properly set the angular variable to the angular library, rather than undefined which is the default behavior.

docs/development/core/development-modules.asciidoc

@@ -0,0 +1,80 @@
+[[development-modules]]
+=== Modules and Autoloading
+
+[float]
+==== Autoloading
+
+Because of the disconnect between JS modules and angular directives, filters,
+and services it is difficult to know what you need to import. It is even more
+difficult to know if you broke something by removing an import that looked
+unused.
+
+To prevent this from being an issue the ui module provides "autoloading"
+modules. The sole purpose of these modules is to extend the environment with
+certain components. Here is a breakdown of those modules:
+
+- *`import 'ui/autoload/styles'`*
+    Imports all styles at the root of `src/ui/public/styles`
+
+- *`import 'ui/autoload/directives'`*
+    Imports all directives in `src/ui/public/directives`
+
+- *`import 'ui/autoload/filters'`*
+    Imports all filters in `src/ui/public/filters`
+
+- *`import 'ui/autoload/modules'`*
+    Imports angular and several ui services and "components" which Kibana
+    depends on without importing. The full list of imports is hard coded in the
+    module. Hopefully this list will shrink over time as we properly map out
+    the required modules and import them were they are actually necessary.
+
+- *`import 'ui/autoload/all'`*
+    Imports all of the above modules
+
+[float]
+==== Resolving Require Paths
+
+Kibana uses Webpack to bundle Kibana's dependencies.
+
+Here is how import/require statements are resolved to a file:
+
+NOTE: if you're familiar with the node.js algorithm, the changes are in *2.ii* and *3.i.f* to *3.i.g*
+
+. Pick an algorithm
+  * if the path starts with a '.'
+    ** append it the directory of the current file
+    ** proceed to *3*
+  * if the path starts with a '/'
+    ** search for this exact path
+    ** proceed to *3*
+  * proceed to *2*
+. Search for a named module
+  * `moduleName` = dirname(require path)`
+  * match if `moduleName` is or starts with one of these aliases
+    ** replace the alias with the match and continue to ***3***
+  * match when any of these conditions are met:
+    ** `./webpackShims/${moduleName}` is a directory
+    ** `./node_modules/${moduleName}` is a directory
+  * if no match was found
+    ** move to the parent directory
+    ** start again at *2.iii* until reaching the root directory or a match is found
+  * if a match was found
+    ** replace the `moduleName` prefix from the require statement with the full path of the match and proceed to *3*
+. Search for a file
+  * the first of the following paths that resolves to a **file** is our match
+    ** path + '.js'
+    ** path + '.json'
+    ** path + '.jsx'
+    ** path + '.less'
+    ** path
+    ** path/${basename(path)} + '.js'
+    ** path/${basename(path)} + '.json'
+    ** path/${basename(path)} + '.jsx'
+    ** path/${basename(path)} + '.less'
+    ** path/${basename(path)}
+    ** path/index + '.js'
+    ** path/index + '.json'
+    ** path/index + '.jsx'
+    ** path/index + '.less'
+    ** path/index
+  * if none of the above paths matches then an error is thrown

docs/development/plugin-development.asciidoc

@@ -0,0 +1,14 @@
+[[plugin-development]]
+== Plugin Development
+
+[IMPORTANT]
+==============================================
+The Kibana plugin interfaces are in a state of constant development.  We cannot provide backwards compatibility for plugins due to the high rate of change.  Kibana enforces that the installed plugins match the version of Kibana itself.  Plugin developers will have to release a new version of their plugin for each new Kibana release as a result.
+==============================================
+
+* <<development-plugin-resources>>
+* <<development-uiexports>>
+
+include::plugin/development-plugin-resources.asciidoc[]
+
+include::plugin/development-uiexports.asciidoc[]

docs/development/plugin/development-plugin-resources.asciidoc

@@ -0,0 +1,28 @@
+[[development-plugin-resources]]
+=== Plugin Resources
+
+Here are some resources that will be helpful for getting started with plugin development
+
+[float]
+==== Our IRC channel
+Many Kibana developers hang out on `irc.freenode.net` in the `#kibana` channel. We *want* to help you with plugin development. Even more than that, we *want your help* in understanding your plugin goals so we can build a great plugin system for you! If you've never used IRC, welcome to the fun. You can get started with the http://webchat.freenode.net/?channels=kibana[Freenode Web Client].
+
+[float]
+==== Some light reading
+- Our {repo}blob/master/CONTRIBUTING.md[contributing guide] can help you get a development environment going
+- Tim Roes' excellent blog series https://www.timroes.de/2016/02/21/writing-kibana-plugins-custom-applications/[Writing Kibana Plugins]
+
+[float]
+==== Videos
+- https://www.elastic.co/elasticon/2015/sf/contributors-guide-to-the-kibana-galaxy[Contributors Guide to the Kibana Galaxy]
+- https://www.elastic.co/elasticon/conf/2016/sf/how-to-build-your-own-kibana-plugins[Kibana Plugin Dev - Elasticon 2016]
+
+[float]
+==== Plugin Generator
+
+Check out the https://github.com/elastic/generator-kibana-plugin[plugin generator] to kick-start your plugin.
+
+[float]
+==== References in the code
+ - {repo}/blob/master/src/server/plugins/plugin.js[Plugin class]: What options does the `kibana.Plugin` class accept?
+ - <<development-uiexports>>: What type of exports are available?

docs/development/plugin/development-uiexports.asciidoc

@@ -0,0 +1,17 @@
+[[development-uiexports]]
+=== UI Exports
+
+An aggregate list of available UiExport types:
+
+[cols="<h,<",options="header",]
+|=======================================================================
+| Type | Purpose
+| hacks | Any module that should be included in every application
+| visTypes | Modules that register providers with the `ui/registry/vis_types` registry.
+| fieldFormats | Modules that register providers with the `ui/registry/field_formats` registry.
+| spyModes | Modules that register providers with the `ui/registry/spy_modes` registry.
+| chromeNavControls | Modules that register providers with the `ui/registry/chrome_nav_controls` registry.
+| navbarExtensions | Modules that register providers with the `ui/registry/navbar_extensions` registry.
+| docViews | Modules that register providers with the `ui/registry/doc_views` registry.
+| app | Adds an application to the system. This uiExport type is defined as an object of metadata rather than just a module id.
+|=======================================================================

docs/index.asciidoc

@@ -12,9 +12,10 @@ release-state can be: released | prerelease | unreleased
 :release-state:  unreleased
 :es-ref:         https://www.elastic.co/guide/en/elasticsearch/reference/master/
 :xpack-ref:      https://www.elastic.co/guide/en/x-pack/current/
-:issue:          https://github.com/elastic/kibana/issues/
-:pull:           https://github.com/elastic/kibana/pull/
-:commit:         https://github.com/elastic/kibana/commit/
+:repo:           https://github.com/elastic/kibana/
+:issue:          {repo}issues/
+:pull:           {repo}pull/
+:commit:         {repo}commit/
 :security:       https://www.elastic.co/community/security/
 
 
@@ -39,3 +40,5 @@ include::console.asciidoc[]
 include::management.asciidoc[]
 
 include::plugins.asciidoc[]
+
+include::development.asciidoc[]

docs/plugins.asciidoc

@@ -126,3 +126,5 @@ you must specify the path to that configuration file each time you use the `bin/
 64:: Unknown command or incorrect option parameter
 74:: I/O error
 70:: Other error
+
+include::plugins/known-plugins.asciidoc[]

docs/plugins/known-plugins.asciidoc

@@ -0,0 +1,41 @@
+[[known-plugins]]
+== Known Plugins
+
+[IMPORTANT]
+.Plugin compatibility
+==============================================
+The Kibana plugin interfaces are in a state of constant development.  We cannot provide backwards compatibility for plugins due to the high rate of change.  Kibana enforces that the installed plugins match the version of Kibana itself.  Plugin developers will have to release a new version of their plugin for each new Kibana release as a result.
+==============================================
+
+This list of plugins is not guaranteed to work on your version of Kibana. Instead, these are plugins that were known to work at some point with Kibana *5.x*. The Kibana installer will reject any plugins that haven't been published for your specific version of Kibana.
+
+[float]
+=== Packs
+* https://www.elastic.co/downloads/x-pack[X-Pack] - security, monitoring, reporting, alerts, graph
+
+[float]
+=== Apps
+* https://github.com/sivasamyk/logtrail[LogTrail] - View, analyze, search and tail log events in realtime with a developer/sysadmin friendly interface
+
+[float]
+=== Timelion Extensions
+* https://github.com/fermiumlabs/mathlion[mathlion] (fermiumlabs) - enables equation parsing and advanced math under Timelion
+
+[float]
+=== Visualizations
+* https://github.com/prelert/kibana-swimlane-vis[Swimlanes] (prelert)
+* https://github.com/sbeyn/kibana-plugin-line-sg[Line] (sbeyn)
+* https://github.com/sbeyn/kibana-plugin-gauge-sg[Gauge] (sbeyn)
+* https://github.com/sbeyn/kibana-plugin-traffic-sg[Traffic] (sbeyn)
+* https://github.com/JuanCarniglia/area3d_vis[3D Graph] (JuanCarniglia)
+* https://github.com/nreese/enhanced_tilemap[Enhanced Tilemap] (nreese)
+* https://github.com/dlumbrer/kbn_network[Network Plugin] (dlumbrer)
+* https://github.com/mstoyano/kbn_c3js_vis[C3JS Visualizations] (mstoyano)
+* https://github.com/clamarque/Kibana_health_metric_vis[Health Metric] (clamarque)
+* https://github.com/ommsolutions/kibana_ext_metrics_vis[Extended Metric] (ommsolutions)
+
+[float]
+=== Other
+* https://github.com/nreese/kibana-time-plugin[Time picker as a dashboard panel] Widget to view and edit the time range from within dashboards.
+
+NOTE: If you want your plugin to be added to this page, open a {repo}tree/{version}/docs/plugins/known-plugins.asciidoc[pull request].