overpass-doc 0.0.1

data/lib/overpass-doc/generator.rb

@@ -0,0 +1,122 @@
+module OverpassDoc
+
+  class Generator
+
+    attr_reader :dir, :queries, :package
+
+    def initialize(dir, output_dir, view_dir=nil, asset_dir=nil)
+      @dir = dir
+      @output_dir = output_dir
+      @asset_dir = asset_dir || File.join( File.dirname( __FILE__ ) , "assets")
+      @view_dir = view_dir || File.join( File.dirname( __FILE__ ) , "views")
+      @package = parse_package()
+      @queries = parse_queries()
+    end
+
+    def read_template(name)
+      File.read(File.join(@view_dir, "#{name}.erb"))
+    end
+
+    def parse_package()
+      package = File.join(@dir, "package.json")
+      if File.exists?(package)
+        return JSON.load( File.open(package) )
+      end
+      Hash.new
+    end
+
+    def parse_queries()
+      queries = []
+      Dir.glob("#{@dir}/*.op") do |file|
+        content = File.read(file)
+        path = file.gsub("#{@dir}/", "")
+        queries << OverpassDoc::Query.new(path, content, @package)
+      end
+      queries.sort! {|x,y| x.title <=> y.title }
+      queries
+    end
+
+    def run()
+      copy_assets()
+      generate_index()
+      generate_query_pages()
+      copy_extra_files()
+    end
+
+    def copy_assets(asset_dir=@asset_dir)
+      $stderr.puts("Copying assets");
+      if !File.exists?(@output_dir)
+        FileUtils.mkdir_p(@output_dir)
+      end
+      FileUtils.cp_r( "#{@asset_dir}/.", @output_dir )
+    end
+
+    def copy_extra_files()
+      @package["extra-files"].each do |file|
+        markup = File.read( File.join(@dir, file) )
+        renderer = Redcarpet::Render::HTML.new({})
+        markdown = Redcarpet::Markdown.new(renderer, {})
+        template = ERB.new( read_template(:extra) )
+        _content = markdown.render(markup)
+        html = layout do
+          b = binding
+          template.result(b)
+        end
+        file = File.join(@output_dir, file.gsub(".md", ".html"))
+        File.open(file, "w") do |f|
+          f.puts html
+        end
+      end if @package["extra-files"]
+    end
+
+    def get_overview()
+      overview = File.join(@dir, "overview.md")
+      if File.exists?( overview )
+        markup = File.read( overview )
+        renderer = Redcarpet::Render::HTML.new({})
+        markdown = Redcarpet::Markdown.new(renderer, {})
+        return markdown.render(markup)
+      end
+      nil
+    end
+
+    def generate_index()
+      $stderr.puts("Generating index.html");
+      _title = @package["title"] || "Overpass Query Documentation"
+      _overview = get_overview()
+      _description = @package["description"] || ""
+      template = ERB.new( read_template(:index) )
+      html = layout do
+        b = binding
+        template.result(b)
+      end
+      File.open(File.join(@output_dir, "index.html"), "w") do |f|
+        f.puts(html)
+      end
+    end
+
+    def layout
+      b = binding
+      _title = @package["title"] || "Overpass Query Documentation"
+      _overview = get_overview()
+      ERB.new( read_template(:layout) ).result(b)
+    end
+
+    def generate_query_pages()
+      template = ERB.new( read_template(:query) )
+      @queries.each do |query|
+        $stderr.puts("Generating docs for #{query.path}")
+        File.open( File.join(@output_dir, query.output_filename), "w" ) do |f|
+          b = binding
+          _title = @package["title"] || "Overpass Query Documentation"
+          _overview = get_overview()
+          html = layout do
+            template.result(b)
+          end
+          f.puts( html )
+        end
+      end
+    end
+
+  end
+end

data/lib/overpass-doc/query.rb

@@ -0,0 +1,119 @@
+module OverpassDoc
+
+  class Query
+
+    attr_reader :path, :query, :raw_query, :package
+
+    PATTERN = %r{(?<multi>/\*(?<multi_content>(.|\n)*?)?\*/)|(?<error>/\*(.*)?)}
+
+    ANNOTATIONS = {
+      :author => {
+        :multi => true
+      },
+      :see => {
+        :multi => true
+      },
+      :tags => {
+        :multi => true
+      },
+      :title => {
+        :multi => false
+      },
+    }
+
+    ANNOTATIONS.each do |var, config|
+      attr_reader(var)
+    end
+
+    def initialize(path, query, package={})
+      ANNOTATIONS.each do |var, config|
+        if config[:multi]
+          instance_variable_set( "@#{var}", [] )
+        else
+          instance_variable_set( "@#{var}", "" )
+        end
+      end
+      @path = path
+      @query = query
+      @raw_query = query
+      @title = @path
+      @description = ""
+
+      ["author", "tag"].each do |annotation|
+        if package[annotation]
+          instance_variable_set( "@#{annotation}", package[annotation])
+        end
+      end
+      parseQuery()
+    end
+
+    def output_filename
+      return "#{path.gsub(".op", "")}.html"
+    end
+
+    def description(html=false)
+      if html
+        renderer = Redcarpet::Render::HTML.new({})
+        markdown = Redcarpet::Markdown.new(renderer, {})
+        return markdown.render(@description)
+      end
+      @description
+    end
+
+    def query_string
+      CGI::escape( @query )
+    end
+
+    def extract_annotation(line)
+      matches = line.lstrip.match(/^@([a-zA-Z]+) *(.+)$/i)
+      return nil unless matches
+      return matches[1], matches[2]
+    end
+
+    private
+
+    def parseQuery
+      match = @raw_query.match(PATTERN)
+      return if match.nil?
+      if match[:error]
+        raise "Invalid query"
+      end
+
+
+      query_lines = []
+      header = true
+      description = false
+      description_lines = []
+
+      match[:multi_content].split("\n").each do |line|
+        if ( header )
+          annotation, value = extract_annotation(line)
+          if ( annotation )
+            config = ANNOTATIONS[ annotation.intern ]
+            if config
+              if config[:multi]
+                val = instance_variable_get("@#{annotation}")
+                val << value.strip
+              else
+                instance_variable_set("@#{annotation}", value.strip)
+              end
+              description = true
+            else
+              $stderr.puts("Ignoring unknown annotation: @#{annotation}")
+            end
+          else
+            if (description == false)
+              description_lines << line.lstrip
+            end
+          end
+        else
+          header = false
+          query_lines << line
+        end
+      end
+      @description = description_lines.join("\n") unless description_lines.empty?
+
+    end
+  end
+
+end

data/lib/overpass-doc/views/extra.erb

@@ -0,0 +1,4 @@
+<div class="container">
+ <%= _content %>
+
+</div>

data/lib/overpass-doc/views/index.erb

@@ -0,0 +1,37 @@
+<div class="container">
+      <div class="bg-light p-5 rounded">
+        	<h1><%= _title %></h1>
+          <p class="lead"><%= _description %></p>
+      </div>
+
+	  <% if _overview %>
+      	<div class="row">
+        	<div class="col">
+        		<h3 id="overview">Overview</h3>
+          		<%= _overview %>
+        	</div>
+      	</div>
+	  <% end %>
+
+      <div class="row">
+        <div class="col">
+          <h3>Queries</h3>
+          <p>This set of documentation covers <strong><%= @queries.size %></strong> queries</p>
+          <table class="table table-hover">
+            <thead>
+            	<tr>
+            		<th>Title</th><th>Source Path</th>
+            	</tr>
+            </thead>
+            <tbody>
+           		<% @queries.each do |query| %>
+           		<tr>
+           		  <td><a href="<%= query.output_filename %>"><%= query.title %></a></td><td><code><%= query.path %></code></td>
+           		</tr>
+           		<% end %>
+			</tbody>
+          </table>
+        </div>
+      </div>
+
+</div>

data/lib/overpass-doc/views/layout.erb

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html class="h-100">
+  <head>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+    <title><%= _title %></title>
+
+    <script src="jquery.js" type="text/javascript"></script>
+	  <script src="bootstrap.min.js" type="text/javascript"></script>
+    <script src="codemirror.js" type="text/javascript"></script>
+	  <script src="mode/clike/clike.js" type="text/javascript"></script>
+	  <script src="util/multiplex.js" type="text/javascript"></script>
+
+    <link rel="stylesheet" href="codemirror.css">
+    <link href="bootstrap.min.css" rel="stylesheet" />
+    <link href="codemirror.css" rel="stylesheet" />
+
+    <style type="text/css">
+      .bd-placeholder-img {
+        font-size: 1.125rem;
+        text-anchor: middle;
+        -webkit-user-select: none;
+        -moz-user-select: none;
+        user-select: none;
+      }
+
+      @media (min-width: 768px) {
+        .bd-placeholder-img-lg {
+          font-size: 3.5rem;
+        }
+      }
+      main > .container {
+        padding: 60px 15px 0;
+      }
+    </style>
+
+  </head>
+
+
+  <body class="d-flex flex-column h-100">
+
+    <header>
+        <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark">
+          <div class="container-fluid">
+            <a class="navbar-brand" href="index.html"><%= _title %></a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
+              <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="navbarCollapse">
+              <ul class="navbar-nav me-auto mb-2 mb-md-0">
+                <% if _overview %>
+                  <li class="nav-item">
+                    <a class="nav-link active" aria-current="page" href="index.html#overview">Overview</a>
+                  </li>
+                <% end %>
+                <% if @package["extra-files"] %>
+        		  	  <% @package["extra-files"].each do |file| %>
+                    <li class="nav-item">
+                      <a class="nav-link" href="<%= file.gsub(".md", ".html") %>"><%= file.gsub(".md", "").capitalize %></a>
+                    </li>
+        		  	  <% end %>
+        		  	<% end %>
+              </ul>
+            </div>
+          </div>
+        </nav>
+    </header>
+
+      <main class="flex-shrink-0">
+       <%= yield %>
+      </main>
+
+       <footer class="footer mt-auto py-3 bg-light">
+         <div class="container">
+           <span class="text-muted">Generated with <a href="http://github.com/ldodds/overpass-doc">overpass-doc</a>.</span>
+         </div>
+       </footer>
+
+
+  </body>
+</html>

data/lib/overpass-doc/views/query.erb

@@ -0,0 +1,115 @@
+<div class="container">
+      <div class="row">
+        <div class="col">
+          <div class="row">
+              <div id="query-viewer">
+					<h2 property="title"><%= query.title %></h2>
+					<% if query.description %>
+						<p property="description"><%= query.description(true) %></p>
+					<% end %>
+					<dl>
+					  <dt>Source File</dt>
+					  <dd><code><%= query.path %></code></dd>
+					  <% query.author.each do |author| %>
+					  <dt>Author</dt>
+					  <dd><span property="creator"><%= author %></span></dd>
+					  <% end %>
+					  <% query.see.each do |see| %>
+					  <dt>Link</dt>
+					  <dd><a href="<%= see %>"><%= see %></a></dd>
+					  <% end %>
+					  <% if query.tags.length > 0 %>
+					  	<dt>Tag</dt>
+					  	<dd>
+					  	   <%= query.tags.map{|x| "<span property=\"subject\">#{x}</span>" }.join(", ") %>
+					  	</dd>
+					  <% end %>
+					</dl>
+					<textarea id="overpass" cols="120" rows="50"><%= query.query %></textarea>
+					<script>
+            CodeMirror.defineMIME("text/x-overpassQL", {
+              name: "clike",
+              keywords: (function (str) {
+                var r = {};
+                var a = str.split(" ");
+                for (var i = 0; i < a.length; i++) r[a[i]] = true;
+                return r;
+              })(
+                "out json xml custom popup timeout maxsize bbox" + // initial declarations
+                  " date diff adiff" + //attic declarations
+                  " foreach" + // block statements
+                  " relation rel way node is_in area around user uid newer changed poly pivot nwr derived" + // queries
+                  " out meta body skel tags ids count qt asc" + // actions
+                  " center bb geom" // geometry types
+                //+"r w n br bw" // recursors
+              )
+            });
+            CodeMirror.defineMIME("text/x-overpassXML", "xml");
+            CodeMirror.defineMode("xml+mustache", function (config) {
+              return CodeMirror.multiplexingMode(
+                CodeMirror.multiplexingMode(CodeMirror.getMode(config, "xml"), {
+                  open: "{{",
+                  close: "}}",
+                  mode: CodeMirror.getMode(config, "text/plain"),
+                  delimStyle: "mustache"
+                }),
+                {
+                  open: "{{style:",
+                  close: "}}",
+                  mode: CodeMirror.getMode(config, "text/css"),
+                  delimStyle: "mustache"
+                }
+              );
+            });
+            CodeMirror.defineMode("ql+mustache", function (config) {
+              return CodeMirror.multiplexingMode(
+                CodeMirror.multiplexingMode(
+                  CodeMirror.getMode(config, "text/x-overpassQL"),
+                  {
+                    open: "{{",
+                    close: "}}",
+                    mode: CodeMirror.getMode(config, "text/plain"),
+                    delimStyle: "mustache"
+                  }
+                ),
+                {
+                  open: "{{style:",
+                  close: "}}",
+                  mode: CodeMirror.getMode(config, "text/css"),
+                  delimStyle: "mustache"
+                }
+              );
+            });
+					  var editor = CodeMirror.fromTextArea(document.getElementById("overpass"), {
+						    height: "250px",
+						    width: "250px",
+						    autofocus: false,
+						    readOnly: true,
+                mode: "ql+mustache",
+						    lineNumbers: true,
+                lineWrapping: true,
+                matchBrackets: true,
+                closeTagEnabled: true,
+                closeTagIndent: [
+                  "osm-script",
+                  "query",
+                  "union",
+                  "foreach",
+                  "difference"
+                ]
+						  });
+					</script>
+          <h3>Test This Query</h3>
+					<p>Try this query in Overpass Turbo:</p>
+					<ul>
+					    <li>
+					      <a href="https://overpass-turbo.eu/?Q=<%= query.query_string %>&R" target="_blank">https://overpass-turbo.eu/</a>
+					    </li>
+					</ul>
+
+              </div>
+          </div><!--/row-->
+        </div><!--/span-->
+      </div><!--/row-->
+
+</div>