Add repository documentation data source

With this commit it becomes possible to define additional data sources
for content pages. The content will be cloned from the specified
repository. Links in these pages will be normalized to work inside the
docs project. It's assumed the documentation pages include the standard
nanoc config options and set :title and optionall :sort_rank.

.gitignore

@@ -5,7 +5,8 @@ output/
 
 # Temporary file directory
 tmp/
-downloads/
+/downloads/
+/repositories/
 
 # Crash Log
 crash.log

Makefile

 DOWNLOADS := prometheus alertmanager blackbox_exporter consul_exporter graphite_exporter haproxy_exporter memcached_exporter mysqld_exporter node_exporter pushgateway statsd_exporter
 
 clean:
-	rm -rf output downloads
+	rm -rf output downloads repositories
 
-compile: clean downloads
+compile:
 	bundle exec nanoc
 
-deploy: github_pages_export github_pages_push
+deploy: clean downloads compile github_pages_export github_pages_push
 
 downloads: $(DOWNLOADS:%=downloads/%/repo.json) $(DOWNLOADS:%=downloads/%/releases.json)
 
@@ -20,7 +20,7 @@ downloads/%/releases.json:
 	@echo "curl -sf -H 'Accept: application/vnd.github.v3+json' <GITHUB_AUTHENTICATION> https://api.github.com/repos/prometheus/$*/releases > $@"
 	@curl -sf -H 'Accept: application/vnd.github.v3+json' $(GITHUB_AUTHENTICATION) https://api.github.com/repos/prometheus/$*/releases > $@
 
-github_pages_export: compile
+github_pages_export:
 	cd output && \
 		mkdir -p .github && \
 		echo "This repository is auto-generated. You have to open pull requests against https://github.com/prometheus/docs instead." > .github/PULL_REQUEST_TEMPLATE.md && \

Rules

@@ -46,6 +46,7 @@ compile '*' do
     # Don't filter; this should propagate verbatim to the output GitHub repository.
   elsif item[:extension] == 'md'
     filter :redcarpet, options: {filter_html: true, autolink: true, no_intraemphasis: true, fenced_code_blocks: true, gh_blockcode: true, tables: true}, renderer_options: {with_toc_data: true}
+    filter :normalize_links, item[:repo_docs] if item[:repo_docs]
     filter :add_anchors
     filter :bootstrappify
     filter :admonition

lib/data_sources/repo_docs.rb

+class RepoDocsDataSource < ::Nanoc::DataSources::FilesystemUnified
+  identifier :repo_docs
+
+  PATH = "repositories"
+
+  def up
+    c = config[:config]
+
+    %x(
+      scripts/checkout.sh \
+        -d "#{docs_root}" \
+        -t "#{repo_path}" \
+        "#{c[:repository]}" "#{c[:refspec]}"
+    )
+    if $?.exitstatus != 0
+      raise "Couldn't checkout repository #{c.inspect}"
+    end
+
+    super
+  end
+
+  def items
+    c = config.fetch(:config)
+    super.map do |item|
+      item[:repo_docs] = c
+      # TODO(ts): Document that repo doc index.md will be ignored.
+      if item.identifier == '/'
+        item[:nav] = { strip: true }
+      end
+      item
+    end
+  end
+
+  def content_dir_name
+    File.join(repo_path, docs_root)
+  end
+
+  def layouts_dir_name
+    'unsupported'
+  end
+
+  private
+
+  def docs_root
+    c = config.fetch(:config)
+    c.fetch(:root, 'docs/')
+  end
+
+  def repo_path
+    c = config.fetch(:config)
+    base = c.fetch(:repo_base, 'repositories')
+    File.join(base, File.basename(c[:repository]), c[:name])
+  end
+end

lib/filters/normalize_links.rb

+# encoding: utf-8
+
+require 'nokogiri'
+
+class NormalizeLinks < ::Nanoc::Filter
+  identifier :normalize_links
+
+  DOMAIN = 'https://prometheus.io'
+
+  def run(content, config = {})
+    doc = Nokogiri::HTML(content)
+    links = doc.xpath('//a')
+
+    links.each do |link|
+      link['href'] =
+        case
+        when link['href'].start_with?(DOMAIN)
+          link['href'][DOMAIN.size..-1]
+        when link['href'].start_with?('/')
+          link_to(link['href'], config)
+        when link['href'].include?('.md')
+          link['href'].gsub(/\.md($|#)/, '/\\1')
+        else
+          link['href']
+        end
+    end
+
+    doc.to_s
+  end
+
+  # TODO(ts): It's not guaranteed that a repository is hosted on Github.
+  def link_to(file, config)
+    base = config[:repository]
+    if base.end_with?('.git')
+      base = base[0..-5]
+    end
+    File.join(base, 'blob', config[:refspec], file)
+  end
+end

lib/helpers/nav.rb

@@ -3,6 +3,14 @@ def nav(root_item, buffer='', layer=0)
 
   children = nav_children(root_item)
 
+  # Strip item from menu.
+  if root_item[:nav] && root_item[:nav][:strip]
+    children.each do |child|
+      nav(child, buffer, layer)
+    end
+    return buffer
+  end
+
   if nav_active?(root_item)
     buffer << "<li class=\"active\">"
   else

scripts/checkout.sh

+#!/bin/bash
+
+usage() {
+me=$(basename $0)
+cat <<EOF
+Usage:
+  $me [ options ] <repository> [ <refspec> ]
+
+Options:
+  -d <directory>  Remote directory name of the sparse-checlout. Default: docs/
+  -t <path>       Target path of the checkout. Default: repository basename
+EOF
+
+exit 1
+}
+
+while getopts 'd:t:' OPT
+do
+  case ${OPT} in
+    d)
+      DIRECTORY="${OPTARG}"
+      ;;
+    t)
+      TARGET="${OPTARG}"
+      ;;
+    *)
+      usage
+      ;;
+  esac
+done
+
+shift $((OPTIND-1))
+
+[ $# -ge 1 ] || usage
+
+REPOSITORY="$1"
+REFSPEC="$2"
+
+if [[ -z "${DIRECTORY}" ]]; then
+    DIRECTORY="docs/"
+fi
+
+if [[ -z "${TARGET}" ]]; then
+    TARGET=$(basename "${REPOSITORY}")
+fi
+
+mkdir -p "${TARGET}"
+cd "${TARGET}"
+
+git init
+
+git config core.sparsecheckout true
+echo "${DIRECTORY}" > .git/info/sparse-checkout
+
+git pull --depth=1 "${REPOSITORY}" "${REFSPEC}"