Merge branch 'master' into feature/add_legend_sideWidth

.circleci/config.yml

@@ -6,7 +6,10 @@ jobs:
       - checkout
       - run:
           name: unit tests
-          command: docker run -w $PWD -v $PWD:$PWD --entrypoint sh sparkprime/jsonnet tests.sh
+          command: make test
+      - run:
+          name: api-docs
+          command: make gen-api-docs
       - run:
           name: docs
           command: docker run --rm -u $UID -it -p 8000:8000 -v $PWD:/docs squidfunk/mkdocs-material build

.gitignore

@@ -1,2 +1,5 @@
 site
+docs/api-docs.md
 *_test_output.json
+e2e/node_modules
+.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Thank you for your interest in contributing to Grafonnet! We welcome all people
+who want to contribute in a healthy and constructive manner within our
+community. Grafonnet is developed within the Grafana community. Therefore we
+are following the same [Code of Conduct as
+Grafana](https://github.com/grafana/grafana/blob/master/CODE_OF_CONDUCT.md). To
+help us create a safe and positive community experience for all, we require all
+participants to adhere to it.
+
+## Plugin Scope
+
+**Grafonnet only aims to support core features and plugins.**
+
+While Grafonnet itself only supports core Grafana functionality, we strongly
+encourage development and use of community Grafonnet extensions. See the
+[Community Plugins](https://grafana.github.io/grafonnet-lib/community-plugins/)
+page for more info on this.

Makefile

@@ -0,0 +1,27 @@
+help:         # Show this message.
+	@echo "\nAvailable Targets:\n"
+	@sed -ne '/@sed/!s/# //p' $(MAKEFILE_LIST)
+
+test:         # Run all unit tests.
+	@docker run --rm \
+		-w $$PWD \
+		-v $$PWD:$$PWD \
+		--entrypoint sh \
+		sparkprime/jsonnet \
+		tests.sh
+
+test-update:  # Run all unit tests while copying test_output.json to compiled.json file.
+	@docker run --rm \
+		-w $$PWD \
+		-v $$PWD:$$PWD \
+		--entrypoint sh \
+		sparkprime/jsonnet \
+		tests.sh update
+
+gen-api-docs: # Generate api-docs.md from source code comments.
+	@docker run --rm \
+		-w $$PWD \
+		-v $$PWD:$$PWD \
+		trotttrotttrott/jsonnetdoc:219e41b \
+		grafonnet --markdown \
+		> docs/api-docs.md

README.md

@@ -1,206 +1,14 @@
-# Grafonnet, a Jsonnet library for generating Grafana dashboards
+# Grafonnet
 
-[![CircleCI](https://circleci.com/gh/grafana/grafonnet-lib.svg?style=svg)](https://circleci.com/gh/grafana/grafonnet-lib)
-
-Grafonnet provides a simple way of writing Grafana dashboards. It leverages the
-data templating language [Jsonnet][jsonnet]. It enables you to write reusable
-components that you can use and reuse for multiple dashboards.
-
-![screenshot](screenshot.png)
-
-## Getting started
-
-### Prerequisites
-
-Grafonnet requires Jsonnet.
-
-#### Linux
-
-You must build the binary. For details, [see the GitHub
-repository][jsonnetgh].
-
-#### Mac OS X
-
-Jsonnet is available in Homebrew. If you do not have Homebrew installed,
-[install it][brew].
-
-Then run:
-
-```
-brew install jsonnet
-```
-
-### Install grafonnet
-
-Clone this git repository:
+A Jsonnet library for generating Grafana dashboards.
 
-```
-git clone https://github.com/grafana/grafonnet-lib.git
-```
-
-Then import the grafonnet in your jsonnet code:
-
-```
-local grafana = import 'grafonnet/grafana.libsonnet';
-```
-
-To be able to find the grafonnet library, you must pass the root of the git
-repository to grafonnet using the `-J` option:
-
-```
-jsonnet -J <path> dashboard.jsonnet
-```
-
-As you build your own mixins/dashboards, you should add additional `-J` paths.
-
-## Examples
-
-Simple Grafana 5.x dashboard:
-
-Please note that the layout has changed, no `row` objects and new possible
-nesting of `panel` objects. You need to set `schemaVersion` parameter on
-dashboard object to at least 16.
-
-```jsonnet
-local grafana = import 'grafonnet/grafana.libsonnet';
-local dashboard = grafana.dashboard;
-local row = grafana.row;
-local singlestat = grafana.singlestat;
-local prometheus = grafana.prometheus;
-local template = grafana.template;
-
-dashboard.new(
-  'JVM',
-  schemaVersion=16,
-  tags=['java'],
-)
-.addTemplate(
-  grafana.template.datasource(
-    'PROMETHEUS_DS',
-    'prometheus',
-    'Prometheus',
-    hide='label',
-  )
-)
-.addTemplate(
-  template.new(
-    'env',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current, env)',
-    label='Environment',
-    refresh='time',
-  )
-)
-.addTemplate(
-  template.new(
-    'job',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current{env="$env"}, job)',
-    label='Job',
-    refresh='time',
-  )
-)
-.addTemplate(
-  template.new(
-    'instance',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current{env="$env",job="$job"}, instance)',
-    label='Instance',
-    refresh='time',
-  )
-)
-.addPanel(
-  singlestat.new(
-    'uptime',
-    format='s',
-    datasource='Prometheus',
-    span=2,
-    valueName='current',
-  )
-  .addTarget(
-    prometheus.target(
-      'time() - process_start_time_seconds{env="$env", job="$job", instance="$instance"}',
-    )
-  ), gridPos={
-    x: 0,
-    y: 0,
-    w: 24,
-    h: 3,
-  }
-)
-```
-
-Simple Grafana 4.x dashboard:
-
-```jsonnet
-local grafana = import 'grafonnet/grafana.libsonnet';
-local dashboard = grafana.dashboard;
-local row = grafana.row;
-local singlestat = grafana.singlestat;
-local prometheus = grafana.prometheus;
-local template = grafana.template;
-
-dashboard.new(
-  'JVM',
-  tags=['java'],
-)
-.addTemplate(
-  grafana.template.datasource(
-    'PROMETHEUS_DS',
-    'prometheus',
-    'Prometheus',
-    hide='label',
-  )
-)
-.addTemplate(
-  template.new(
-    'env',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current, env)',
-    label='Environment',
-    refresh='time',
-  )
-)
-.addTemplate(
-  template.new(
-    'job',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current{env="$env"}, job)',
-    label='Job',
-    refresh='time',
-  )
-)
-.addTemplate(
-  template.new(
-    'instance',
-    '$PROMETHEUS_DS',
-    'label_values(jvm_threads_current{env="$env",job="$job"}, instance)',
-    label='Instance',
-    refresh='time',
-  )
-)
-.addRow(
-  row.new()
-  .addPanel(
-    singlestat.new(
-      'uptime',
-      format='s',
-      datasource='Prometheus',
-      span=2,
-      valueName='current',
-    )
-    .addTarget(
-      prometheus.target(
-        'time() - process_start_time_seconds{env="$env", job="$job", instance="$instance"}',
-      )
-    )
-  )
-)
-```
+[![CircleCI](https://circleci.com/gh/grafana/grafonnet-lib.svg?style=svg)](https://circleci.com/gh/grafana/grafonnet-lib)
 
-Find more examples in the [examples](examples/) directory.
+See the full docs here: https://grafana.github.io/grafonnet-lib/
 
+## Contributing
 
-[brew]:https://brew.sh/
-[jsonnet]:http://jsonnet.org/
-[jsonnetgh]:https://github.com/google/jsonnet
+Please contribute! If you're interested, please start by reading the
+[contributing guide](CONTRIBUTING.md). Before you begin work please take note of
+our code of conduct and ensure that what you'd like to contribute is within the
+scope of what Grafonnet attempts to support.

docs/community-plugins.md

@@ -0,0 +1,21 @@
+# Community Plugins
+
+Jsonnet makes it easy to patch an existing library. Although Grafonnet only
+supports core Grafana features and plugins, it is easy to extend. For example:
+
+```jsonnet
+local grafonnet = (import 'grafonnet-lib/grafana.libsonnet')
+                  + (import 'my-plugin-lib/my-plugin.libsonnet');
+{
+  ...
+}
+```
+
+## Plugin List
+
+If you've developed a Grafonnet extension for supporting a community plugin,
+please submit a pull request to get it added to this list.
+
+* [Status panel (by Vonage)](https://grafana.com/grafana/plugins/vonage-status-panel) template plugin: [link](https://github.com/DifferentialOrange/grafonnet-status-panel).
+* [Statusmap panel (by Flant)](https://grafana.com/grafana/plugins/flant-statusmap-panel) template plugin: [link](https://github.com/blablacar/grafonnet-lib-plugins).
+* [Polystat panel (by Grafana Labs)](https://grafana.com/grafana/plugins/grafana-polystat-panel) template plugin: [link](https://github.com/thelastpickle/grafonnet-polystat-panel).