Merge pull request #296 from prometheus/toc

Table of contents

Rules

@@ -46,6 +46,7 @@ compile '*' do
     filter :bootstrappify
     filter :admonition
     filter :colorize_syntax, :default_colorizer => :pygmentsrb
+    filter :toc, style: item[:toc]
     if item[:kind] == 'article'
       layout 'blog'
     else

content/docs/concepts/metric_types.md

@@ -5,17 +5,11 @@ sort_rank: 2
 
 # Metric types
 
-The Prometheus client libraries offer four core metric types:
-
-  * Counter
-  * Gauge
-  * Histogram
-  * Summary
-
-These metric types are currently only differentiated in the client libraries
-(to enable APIs tailored to the usage of the specific types) and in the wire
-protocol. The Prometheus server does not yet make use of the type information
-and flattens all data into untyped time series. This may change in the future.
+The Prometheus client libraries offer four core metric types. These are
+currently only differentiated in the client libraries (to enable APIs tailored
+to the usage of the specific types) and in the wire protocol. The Prometheus
+server does not yet make use of the type information and flattens all data into
+untyped time series. This may change in the future.
 
 ## Counter
 

content/docs/introduction/faq.md

 ---
 title: FAQ
 sort_rank: 5
+toc: full-width
 ---
 
 # Frequently Asked Questions

content/docs/operating/configuration.md

@@ -72,7 +72,7 @@ scrape_configs:
 ```
 
 
-### Scrape configurations `<scrape_config>`
+### `<scrape_config>`
 
 A `scrape_config` section specifies a set of targets and parameters describing how
 to scrape them. In the general case, one scrape configuration specifies a single
@@ -195,7 +195,7 @@ Where `<scheme>` may be `http` or `https` and `<path>` is a valid URL path.
 regex `[a-zA-Z_][a-zA-Z0-9_-]`.
 
 
-### TLS configuration `<tls_config>`
+### `<tls_config>`
 
 A `tls_config` allows configuring TLS connections.
 
@@ -212,7 +212,7 @@ A `tls_config` allows configuring TLS connections.
 ```
 
 
-### Target groups `<target_group>`
+### `<target_group>`
 
 A `target_group` allows specifying a list of targets and a common label set for them.
 They are the canonical way to specify static targets in a scrape configuration.
@@ -231,7 +231,7 @@ Where `<host>` is a valid string consisting of a hostname or IP followed by a po
 number.
 
 
-### DNS-SD configurations `<dns_sd_config>`
+### `<dns_sd_config>`
 
 A DNS-SD configuration allows specifying a set of DNS record names which
 are periodically queried to discover a list of targets (host-port pairs). The
@@ -259,7 +259,7 @@ names:
 Where `<record_name>` is any DNS SRV record name.
 Where `<query_type>` is `SRV`, `A`, or `AAAA`.
 
-### Consul SD configurations `<consul_sd_config>`
+### `<consul_sd_config>`
 
 Consul SD configurations allow retrieving scrape targets from [Consul's](https://www.consul.io)
 Catalog API.
@@ -300,7 +300,7 @@ Consul setups, the relevant address is in `__meta_consul_service_address`.
 In those cases, you can use the [relabel](#target-relabeling-relabel_config)
 feature to replace the special `__address__` label.
 
-### Kubernetes SD configurations `<kubernetes_sd_config>`
+### `<kubernetes_sd_config>`
 
 CAUTION: Kubernetes SD is in beta: breaking changes to configuration are still
 likely in future releases.
@@ -363,7 +363,7 @@ tls_config:
 [ retry_interval: <duration> | default = 1s ]
 ```
 
-### Marathon SD configurations `<marathon_sd_configs>`
+### `<marathon_sd_configs>`
 
 CAUTION: Marathon SD is in beta: breaking changes to configuration are still
 likely in future releases.
@@ -399,7 +399,7 @@ Prometheus relabeling to control which instances will actually be scraped. Also
 by default all apps will show up as a single job in Prometheus (the one specified
 in the configuration file), which can also be changed using relabeling.
 
-### Zookeeper Serverset SD configurations `<serverset_sd_config>`
+### `<serverset_sd_config>`
 
 Serverset SD configurations allow retrieving scrape targets from [Serversets]
 (https://github.com/twitter/finagle/tree/master/finagle-serversets) which are
@@ -429,7 +429,7 @@ paths:
 
 Serverset data must be in the JSON format, the Thrift format is not currently supported.
 
-### EC2 SD configurations `<ec2_sd_config>`
+### `<ec2_sd_config>`
 
 CAUTION: EC2 SD is in beta: breaking changes to configuration are still
 likely in future releases.
@@ -466,7 +466,7 @@ region: <string>
 [ port: <int> | default = 80 ]
 ```
 
-### File-based SD configurations `<file_sd_config>`
+### `<file_sd_config>`
 
 File-based service discovery provides a more generic way to configure static targets
 and serves as an interface to plug in custom service discovery mechanisms.
@@ -510,7 +510,7 @@ Where `<filename_pattern>` may be a path ending in `.json`, `.yml` or `.yaml`. T
 may contain a single `*` that matches any character sequence, e.g. `my/path/tg_*.json`.
 
 
-### Target relabeling `<relabel_config>`
+### `<relabel_config>`
 
 Relabeling is a powerful tool to dynamically rewrite the label set of a target before
 it gets scraped. Multiple relabeling steps can be configured per scrape configuration.
@@ -578,7 +578,7 @@ the `replace`, `keep`, `drop` and `labelmap` actions. The regex is fully anchore
    to label names given by `replacement` with match group references
   (`${1}`, `${2}`, ...) in `replacement` substituted by their value.
 
-### Metric relabeling `<metric_relabel_configs>`
+### `<metric_relabel_configs>`
 
 Metric relabeling is applied to samples as the last step before ingestion. It
 has the same configuration format and actions as target relabeling. Metric

content/docs/querying/functions.md

@@ -11,7 +11,7 @@ sort_rank: 3
 `abs(v vector)` returns the input vector with all sample values converted to
 their absolute value.
 
-## `absent(v vector)`
+## `absent()`
 
 `absent(v vector)` returns an empty vector if the vector passed to it has any
 elements and a 1-element vector with the value 1 if the vector passed to it has
@@ -20,11 +20,16 @@ no elements.
 In the second case, `absent()` tries to be smart about deriving labels of
 the 1-element output vector from the input vector:
 
-| Expression                                       | Result
-|--------------------------------------------------|--------
-| absent(nonexistent{job="myjob"})                 | {job="myjob"}
-| absent(nonexistent{job="myjob",instance=~".*"})  | {job="myjob"}
-| absent(sum(nonexistent{job="myjob"}))            | {}
+```
+absent(nonexistent{job="myjob"})
+# => {job="myjob"}
+
+absent(nonexistent{job="myjob",instance=~".*"})
+# => {job="myjob"}
+
+absent(sum(nonexistent{job="myjob"}))
+# => {}
+```
 
 This is useful for alerting on when no time series
 exist for a given metric name and label combination.
@@ -301,7 +306,7 @@ sample value.
 
 `vector(s scalar)` returns the scalar `s` as a vector with no labels.
 
-## `<aggregation>_over_time()`: Aggregating values over time:
+## `<aggregation>_over_time()`
 
 The following functions allow aggregating each series of a given range vector
 over time and return an instant vector with per-series aggregation results:

layouts/docs.html

@@ -5,7 +5,7 @@
     <div class="col-md-3 side-nav-col">
       <ul class="nav navbar-nav side-nav">
         <% @items['/docs/'].children.sort_by { |i| i[:sort_rank] || 0 }.each do |i| %>
-          <%= toc(i, @item) %>
+          <%= nav(i, @item) %>
         <% end %>
       </ul>
     </div>

lib/filters/toc.rb

+# encoding: utf-8
+
+require 'nokogiri'
+
+class TocFilter < ::Nanoc::Filter
+  identifier :toc
+
+  # Number of items required to render a table of contents.
+  TOC_MINIMUM = 2
+
+  def run(content, params={})
+    doc = Nokogiri::HTML(content)
+    titles = doc.xpath('//h1')
+    headers = doc.xpath('//h2|//h3')
+
+    if titles.empty? || headers.length < TOC_MINIMUM
+      return content
+    end
+
+    style = params[:style] || 'right'
+    items = headers.map do |header|
+      title = header.inner_html.sub(/^(.*)<a .*$/, '\1')
+      { :level => header.name, :title => title, :id => header['id'] }
+    end
+
+    titles.first.after(%(<div class="toc toc-#{style}">#{toc(items)}</div>))
+    doc.to_s
+  end
+
+  def toc(items)
+    return '' if items.empty?
+
+    level = ''
+    table = []
+    items.each do |item|
+      if item[:level] > level
+        table << '<ul>'
+      elsif item[:level] < level
+        table << '</ul>'
+      end
+      level = item[:level]
+
+      table << %(<li><a href="##{item[:id]}">#{item[:title]}</a></li>)
+    end
+    table << '</ul>'
+
+    table.join('')
+  end
+end

lib/helpers/toc.rb → lib/helpers/nav.rb

@@ -2,7 +2,7 @@ def nav_title_of(i)
   i[:nav_title] || i[:title] || ''
 end
 
-def toc(root_item, focused_item, buffer='', layer=0)
+def nav(root_item, focused_item, buffer='', layer=0)
   # Skip non-written or hidden items
   return buffer if root_item.nil? || root_item.path.nil? || root_item[:is_hidden]
 
@@ -30,7 +30,7 @@ def toc(root_item, focused_item, buffer='', layer=0)
     buffer << '<ul class="nav">'
 
     visible_children.each do |child|
-      toc(child, focused_item, buffer, layer + 1)
+      nav(child, focused_item, buffer, layer + 1)
     end
 
     buffer << '</ul>'

static/docs.css

@@ -201,6 +201,27 @@ a.sc-logo img {
   display: block;
 }
 
+.toc {
+  padding: 1em;
+  background-color: #eee;
+}
+
+.toc-right {
+  float: right;
+  width: 40%;
+  margin: 0 0 0.5em 0.5em;
+}
+
+.toc ul {
+  padding: 0 0 0 1.5em;
+  margin: 0;
+}
+
+.toc a code {
+  color: #337ab7;
+  background-color: transparent;
+}
+
 pre {
   font-family: "Courier New", Monaco, Menlo, Consolas, monospace;
   background-color: #444;