Improve documentation

Author: amotl

README.rst

@@ -103,36 +103,16 @@ Before running ``grafana-wtf``, define URL and access token of your Grafana inst
     export GRAFANA_TOKEN=eyJrIjoiWHg...dGJpZCI6MX0=
 
 
-Searching for strings
-=====================
-
-Find the string ``weatherbase`` throughout all dashboards and data sources::
-
-    grafana-wtf find weatherbase
-
-.. note::
-
-    ``grafana-wtf`` will cache HTTP responses for 300 seconds by default.
-    When running it with the ``--drop-cache`` option, it will drop its cache upfront.
-
-
-Replacing strings
-=================
-
-Replace all occurrences of ``ldi_v2`` with ``ldi_v3`` within dashboard with
-UID ``_JJ22OZZk``::
-
-    grafana-wtf --select-dashboard=_JJ22OZZk replace ldi_v2 ldi_v3
-
-
-Displaying changes / revision logs
-==================================
+General information
+===================
 
-Watching out for recent editing activity on any dashboards?
 ::
 
-    # Display 50 most recent changes across all dashboards.
-    grafana-wtf log --number=50
+    # Display a bunch of meta information and statistics.
+    grafana-wtf info --format=yaml
+
+    # Display Grafana version.
+    grafana-wtf info --format=json | jq -r '.grafana.version'
 
 
 Explore data sources
@@ -161,15 +141,37 @@ How to find dashboards which use non-existing data sources?
     grafana-wtf explore dashboards --format=json | jq '.[] | select( .datasources_missing ) | .dashboard + {ds_missing: .datasources_missing[] | [.name]}'
 
 
-Display common information and statistics
-=========================================
+Searching for strings
+=====================
+
+Find the string ``weatherbase`` throughout all dashboards and data sources::
+
+    grafana-wtf find weatherbase
+
+.. note::
+
+    ``grafana-wtf`` will cache HTTP responses for 300 seconds by default.
+    When running it with the ``--drop-cache`` option, it will drop its cache upfront.
+
+
+Replacing strings
+=================
+
+Replace all occurrences of ``ldi_v2`` with ``ldi_v3`` within dashboard with
+UID ``_JJ22OZZk``::
+
+    grafana-wtf --select-dashboard=_JJ22OZZk replace ldi_v2 ldi_v3
+
+
+Display edit history
+====================
+
+Watching out for recent editing activity on any dashboards?
 ::
 
-    # Display a bunch of meta information and statistics.
-    grafana-wtf info --format=yaml
+    # Display 50 most recent changes across all dashboards.
+    grafana-wtf log --number=50
 
-    # Display Grafana version.
-    grafana-wtf info --format=json | jq -r '.grafana.version'
 
 
 ********

doc/backlog.rst

@@ -9,14 +9,13 @@ Prio 1
 - [o] Dockerize
 - [o] Statistics reports for data sources and panels: https://github.com/panodata/grafana-wtf/issues/18
 - [o] Finding invalid data sources: https://github.com/panodata/grafana-wtf/issues/19
+- [o] Add test fixture for adding dashboards at runtime from branch ``amo/test-dashboard-runtime``
 
 
 ********
 Prio 1.5
 ********
-- [o] Check if we can collect metrics from Grafana
-      - https://grafana.com/docs/grafana/latest/administration/view-server/internal-metrics/
-      - https://grafana.com/docs/grafana/latest/developers/plugins/backend/#collect-metrics
+- [o] Search through more Grafana entities (users, organizations, teams)
 - [o] Add test fixture which completely resets everything in Grafana before running the test harness.
       Move to a different port than 3000 then!
 - [o] Improve output format handling and error cases
@@ -37,6 +36,9 @@ Prio 2
 - [o] grafana-wtf log --tail | discourse
 - [o] grafana-wtf log --tail | wtee
 - [o] grafana-wtf export/import
+- [o] Check if we can collect metrics from Grafana
+      - https://grafana.com/docs/grafana/latest/administration/view-server/internal-metrics/
+      - https://grafana.com/docs/grafana/latest/developers/plugins/backend/#collect-metrics
 
 
 ****

grafana_wtf/commands.py

@@ -56,7 +56,33 @@ def run():
       Likewise, use "GRAFANA_TOKEN" instead of "--grafana-token"
       for propagating the Grafana API Key.
 
-    Search examples:
+
+    General information:
+
+      # Display a bunch of meta information and statistics.
+      grafana-wtf info --format=yaml
+
+      # Display Grafana version.
+      grafana-wtf info --format=json | jq -r '.grafana.version'
+
+    Explore data sources:
+
+      # Display all data sources and the dashboards using them, as well as unused data sources.
+      grafana-wtf explore datasources --format=yaml
+
+      # Display names of unused datasources as a flat list.
+      grafana-wtf explore datasources --format=json | jq -r '.unused[].datasource.name'
+
+    Explore dashboards:
+
+      # Display some details of all dashboards, including names of missing data sources.
+      grafana-wtf explore dashboards --format=yaml
+
+      # Display only dashboards which have missing data sources, along with their names.
+      grafana-wtf explore dashboards --format=json | jq '.[] | select( .datasources_missing ) | .dashboard + {ds_missing: .datasources_missing[] | [.name]}'
+
+
+    Find dashboards and data sources:
 
       # Search through all Grafana entities for string "ldi_readings".
       grafana-wtf --grafana-url=https://daq.example.org/grafana/ --grafana-token=eyJrIjoiWHg...dGJpZCI6MX0= find ldi_readings
@@ -78,12 +104,12 @@ def run():
       # Output search results in tabular format.
       grafana-wtf find luftdaten --format=tabular:psql
 
-    Replace examples:
+    Replace labels within dashboards:
 
       # Replace string within specific dashboard.
       grafana-wtf --select-dashboard=_JJ22OZZk replace grafana-worldmap-panel grafana-map-panel
 
-    History examples:
+    Display edit history:
 
       # Display 50 most recent changes across all dashboards.
       grafana-wtf log --number=50
@@ -97,22 +123,6 @@ def run():
       # Output full history table in Markdown format
       grafana-wtf log --format=tabular:pipe
 
-    Explore data sources:
-
-      # Display all data sources and the dashboards using them, as well as unused data sources.
-      grafana-wtf explore datasources --format=yaml
-
-      # Display names of unused datasources as a flat list.
-      grafana-wtf explore datasources --format=json | jq -r '.unused[].datasource.name'
-
-    Explore dashboards:
-
-      # Display some details of all dashboards, including names of missing data sources.
-      grafana-wtf explore dashboards --format=yaml
-
-      # Display only dashboards which have missing data sources, along with their names.
-      grafana-wtf explore dashboards --format=json | jq '.[] | select( .datasources_missing ) | .dashboard + {ds_missing: .datasources_missing[] | [.name]}'
-
     """
 
     # Parse command line arguments