transform-docs.rb

#!/usr/bin/env ruby
# encoding: utf-8

require 'json'

def die(msg)
  $stderr.puts msg
  exit 2
end

def assert(check)
  if !check
    die("Failed check")
  end
end

def typeof(param)
  if param["type"]
    param["type"]
  elsif param["choices"]
    param["choices"].map { |c| c["type"] }.join("|")
  else
    "unknown"
  end
end

def desc(d)
  res = if d[-1] == "."
    d
  else
    "#{d}."
  end
  fixup(res)
end

def fixup(desc)
  desc.gsub!(/<code>/, "``")
  desc.gsub!(/<\/code>/, "``")
  desc.gsub!(/TelemetryController\.jsm/,
             "`TelemetryController.jsm <https://searchfox.org/mozilla-central/rev/330daedbeac2bba296d663668e0e0cf248bc6823/toolkit/components/telemetry/app/TelemetryController.jsm#165-187>`_")
  desc.gsub!(/ScalarData/, "ScalarData_")
  desc.gsub!(/EventData/, "EventData_")
  desc.gsub!(/back-end/, "backend")

  desc
end

def function_head(json)
  assert json["type"] == "function"

  fn_name = json["name"]
  full_fn_name = "browser.telemetry.#{fn_name}"
  params = json["parameters"].map { |p| p["name"] }.join(", ")

  "#{full_fn_name}(#{params});"
end

def argument_list(json)
  assert json["type"] == "function"

  out = ""
  parameters = json["parameters"]
  parameters.each do |param|
    out << "* ``#{param["name"]}`` - *("
    if param["optional"] || (param["type"] == "object" && param["properties"])
      out << "optional, "
    end
    out << typeof(param)
    out << ")* "

    out << desc(param["description"])

    if param["type"] == "object"
      props = param["properties"]
      if props
        out << "\n\n"
        props.each do |(name, prop)|
          out << "  * ``#{name}`` - *("
          if prop["optional"]
            out << "optional, "
          end
          out << prop["type"]
          out << ")* "
          out << desc(prop["description"])
          out << "\n"
        end
      end
    end
    out << "\n"
  end

  out
end

def collect_functions(json)
  json[1]["functions"]
end

def collect_types(json)
  json[1]["types"]
end

PAGE_HEAD = <<EOF
.. _webextension-telemetry:

==============================
WebExtension API for Telemetry
==============================

EOF

json = JSON.parse(IO.read(ARGV.first))

puts PAGE_HEAD
puts fixup(json[1]["description"])
puts

puts "Types"
puts "-----"
puts
types = collect_types(json)
types.each do |typ|
  head = "``#{typ["id"]}``"
  puts head
  puts "~"*head.size
  puts
  puts fixup(typ["description"])
  puts
  if typ["properties"]
    puts "Properties:"
    puts
    out = ""
    typ["properties"].each do |(name, prop)|
      out << "* ``#{name}`` - "
      if prop["$ref"]
        out << "See #{prop["$ref"]}_.\n"
      else
        out << "*("
        if prop["optional"]
          out << "optional, "
        end
        out << prop["type"]
        out << ")* "
        out << desc(prop["description"])
        out << "\n"
      end
    end
    puts out
    puts
  end
end

puts "Functions"
puts "---------"
puts
fns = collect_functions(json)
fns.each do |f|
  head = "``#{f["name"]}``"
  puts head
  puts "~"*head.size
  puts
  puts ".. code-block:: js"
  puts
  puts "  #{function_head(f)}"
  puts
  puts "#{fixup f["description"]}"
  puts
  puts argument_list(f)
  puts
end