overpass-doc 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09dc2dab218ef799c024d923e6892bed2cb74be7c557b35b9e948cfe7782c514'
-  data.tar.gz: d5e31bd7a8734a52c00fe9403f06482ab0ce813a0e90f8d80c5064d2c8e0e5ad
+  metadata.gz: 9fe57639d0bde35c080d670d1cf3e3f554908ba18722a4e1724f1c2ca225899d
+  data.tar.gz: cb2986b10059b85fc5b3c89c786b19ce7f3df406596b151d005f4bd23245f21c
 SHA512:
-  metadata.gz: 72df74a6ce87ac2f9dd53f9599322f43ebf0e00d7f4618d0734f664c9c5425e9553cee09b74699d4d8cf0d42a1812b75c79bb73760b73257d3349fd5464edc69
-  data.tar.gz: 86398341c02b2bf7d137b10bb085710ddc3dd2acd17a47357b3ae55a80d0652212dffb19da24b18547244d4a2c38c716bada6b156fe49b7b834366a4bcf9747f
+  metadata.gz: 579de47255bdd080218e1028594ea92f7656cd96ad9ff26e56097c23ea6d79218437c69d7eb761cea168caeec6255935bf1ee696e367aaa7dec02d2fa0dc4d44
+  data.tar.gz: 1d9291ccd32817d62e97a887b856188e9cfda505f6d242f1a8f92f7772066cd7420c903523f997c11155ee72e2f3a7c2cc3688bfaa5cecb203c44c03dc731b77

data/README.md

@@ -1 +1,195 @@
-# Generate HTML documentation from Overpass queries
+# Generate HTML documentation for OSM Overpass queries
+
+`overpass-doc` provides a simple tool for generating browsable HTML documentation
+from Overpass queries.
+
+It's intended to support people in producing tutorials and training material
+to help people learn how to query OpenStreetmap. It may also be helpful to local
+communities or projects that regularly need to share and run queries. For example to
+help monitor changes in their area, or identify mapping tasks.
+
+## Documenting Overpass queries
+
+`overpass-doc` supports markup for documenting Overpass QL queries, as well as a
+package metadata for a collection of queries.
+
+These features are described in the next sections.
+
+### Overpass QL Documentation Extensions
+
+`overpass-doc` processes your Overpass queries, saved as text files with a `.op` extension.
+
+It then looks for a comment at the top of the query. Like Javadoc, rdoc and
+similar tools, the content of those comments are used to provide metadata
+
+All simple documentation lines at the start of a query will be treated as its description. E.g:
+
+```
+/*
+This is a description
+of my query. It has multiple
+lines
+*/
+```
+
+Special tag can be used to specify other metadata, such as the title of a query:
+
+```
+/*
+This is a description
+of my query. It has multiple
+lines
+@title This is the title
+*/
+```
+
+The full list of supported tags is:
+
+* `@title`: should have a single value. Last title tag wins
+* `@author`: author(s) of the query.
+* `@see`: add one or more links
+* `@tags`: add a tag to a query. Multiple values
+
+Here's an example that uses all these:
+
+```
+/*
+Specifies a bounding box to query for glacier data in a specific area of
+Switzerland.
+
+@title Extract glacier features as a specific location
+@author Leigh Dodds
+@see https://en.wikipedia.org/wiki/Upper_Grindelwald_Glacier
+@tags glacier
+*/
+[out:json][timeout:25][bbox:46.5914,8.0828,46.6301, 8.1674];
+// gather results
+(
+  // query part for: “natural=glacier”
+  node["natural"="glacier"];
+  way["natural"="glacier"];
+  relation["natural"="glacier"];
+);
+// print results
+out body;
+>;
+out skel qt;
+```
+
+The query description can be written in [Markdown](http://daringfireball.net/projects/markdown/). So
+you can include embedded markup, e.g. links, that help to further document a query.
+
+### Overview Documentation
+
+When processing a directory of queries, `overpass-doc` will automatically look for a file called
+`overview.md`. If found, this file will be automatically parsed as Markdown and its contents included
+in an Overview section on the homepage of the documentation.
+
+While the `description` in the `package.json` file is intended to provide a one line summary of the
+package, the `overview.md` file is intended to provide a more detailed introduction. Both are optional,
+so authors can choose which approach they prefer.
+
+### Package Metadata
+
+`overpass-doc` considers a directory of queries to be a _package_. Metadata that describes a package
+and how its documentation should be generated is provided by a valid JSON file called `package.json` which
+is found in the same directory.
+
+The following example of a package.json file shows how to provide a title and a short description
+of a package of files. The title and description will automatically be injected into the documentation.
+
+```
+{
+ "title": "Sample OSM Queries",
+ "description": "A useful selection of queries for beginners"
+}
+```
+
+It is common for a collection of queries to be written by the same person, be tagged in the same
+way, or be useful against the same collection of endpoints. Rather than repeatedly apply the
+`@author`, `@tags` and `@endpoint` annotations to all queries in a package, default values can be
+specified in the `package.json` file.
+
+The following example shows how to do this:
+
+```
+{
+ "title": "Sample OSM Queries",
+ "description": "A useful selection of queries for beginners"
+ "author": ["Leigh Dodds"],
+}
+```
+
+Note that because `@author`, `@tags` and `@see` are all multi-valued annotations, their values
+must be specified as a JSON array.
+
+The `package.json` file can also be used to indicate that extra files in the query directory should be
+processed and included in the documentation. E.g.:
+
+```
+{
+  "title": "Sample OSM Queries",
+   "description": "A useful selection of queries for beginners"
+ "extra-files": ["more-info.md"]
+}
+```
+
+This will trigger `overpass-doc` to process the `more-info.md` file as Markdown, converting it to
+`more-info.html` which is added to the output directory. A link to `more-info` will be automatically
+added to the header navigation
+
+## Example
+
+Here's [some example output](https://ldodds.github.io/osm-queries/) using the example queries included in the project.
+
+## Installation
+
+`overpass-doc` is available as a gem:
+
+	gem install overpass-doc
+
+### Manual Install
+
+You'll need to make sure you have the following installed:
+
+* Ruby 2.5.0+
+* RubyGems
+* Bundler
+* Rake
+
+Once you have those installed, clone the repository and run the provided rake targets to build and install the gem
+locally:
+
+	git clone https://github.com/ldodds/overpass-doc.git
+	cd overpass-doc
+
+The code uses two gems which you'll need to have installed: JSON and [Redcarpet](https://github.com/vmg/redcarpet):
+
+	bundle install
+
+Once installed you should be able to run the `bin/overpass-doc` command-line tool.
+
+## Usage
+
+_Note: the command-line syntax is likely to change in future. E.g. to add more options and/or other commands_
+
+This takes two parameters:
+
+* The input directory. The tool will process all `.op` files in that directory
+* The output directory. All HTML output and required assets will be placed here
+
+The output directory is optional. If not specified it will create a directory called
+`overpass-doc` in the current directory.
+
+E.g. you can run:
+
+	overpass-doc queries pages
+
+This will generate documentation from the bundled examples and place it into the specified
+directory.
+
+## License
+
+This work is hereby released into the Public Domain.
+
+To view a copy of the public domain dedication, visit http://creativecommons.org/licenses/publicdomain or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

data/lib/overpass-doc.rb

@@ -6,4 +6,5 @@ require 'fileutils'
 require 'redcarpet'
 
 require 'overpass-doc/query'
+require 'overpass-doc/package'
 require 'overpass-doc/generator'

data/lib/overpass-doc/generator.rb

@@ -9,38 +9,31 @@ module OverpassDoc
       @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()
+      @package = OverpassDoc::Package.new(@dir)
+      @templates = {}
     end
 
-    def read_template(name)
-      File.read(File.join(@view_dir, "#{name}.erb"))
+    def run
+      copy_assets
+      @package.generate(self)
+    rescue => e
+      puts e
+      puts e.backtrace
     end
 
-    def parse_package()
-      package = File.join(@dir, "package.json")
-      if File.exists?(package)
-        return JSON.load( File.open(package) )
-      end
-      Hash.new
+    def read_template(name)
+      return @templates[name] if @templates[name]
+      @templates[name] = File.read(File.join(@view_dir, "#{name}.erb"))
+      return @templates[name]
     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)
+    def write_file(package, filename, content)
+      if File.dirname(filename) != "."
+        FileUtils.mkdir_p File.join(@output_dir, File.dirname(filename))
+      end
+      File.open(File.join(@output_dir, filename), "w") do |f|
+        f.puts(content)
       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)
@@ -51,72 +44,5 @@ module OverpassDoc
       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/package.rb

@@ -0,0 +1,111 @@
+module OverpassDoc
+  #A directory containing a package.json, query files and supporting assets
+  class Package
+    attr_reader :dir, :queries, :metadata
+
+    def initialize(src_dir)
+      @dir = src_dir
+      @metadata = parse_metadata()
+      @queries = parse_queries()
+    end
+
+    def generate(generator)
+      generate_index(generator)
+      generate_query_pages(generator)
+      copy_extra_files(generator)
+    end
+
+    private
+
+    def parse_metadata()
+      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, @metadata)
+      end
+      queries.sort! {|x,y| x.title <=> y.title }
+      queries
+    end
+
+    def copy_extra_files(generator)
+      @metadata["extra-files"].each do |file|
+        markup = File.read( File.join(@dir, file) )
+        _content = render_markdown(markup)
+        template = ERB.new( generator.read_template(:extra) )
+        html = layout(generator) do
+          b = binding
+          template.result(b)
+        end
+        filename = file.gsub(".md", ".html")
+        generator.write_file(self, filename, html)
+      end if @metadata["extra-files"]
+    end
+
+    #available in template
+    def overview
+      return @overview if @overview
+      overview = File.join(@dir, "overview.md")
+      if File.exists?( overview )
+        markup = File.read( overview )
+        @overview = render_markdown(markup)
+        return @overview
+      end
+      nil
+    end
+
+    def generate_index(generator)
+      $stderr.puts("Generating index.html")
+      generator.write_file(self, "index.html", render_with_layout(generator, :index))
+    end
+
+    def render_markdown(src)
+      renderer = Redcarpet::Render::HTML.new({})
+      markdown = Redcarpet::Markdown.new(renderer, {})
+      markdown.render(src)
+    end
+
+    def render_with_layout(generator, template, variables={})
+      template = ERB.new( generator.read_template(template) )
+      b = binding
+      variables.each do |key, value|
+        b.local_variable_set(key, value)
+      end
+      html = layout(generator) do
+        template.result(b)
+      end
+      return html
+    end
+
+    def layout(generator)
+      b = binding
+      ERB.new( generator.read_template(:layout) ).result(b)
+    end
+
+    #available in template
+    def title
+      @metadata["title"] || "Overpass Query Documentation"
+    end
+
+    def description
+      @metadata["description"] || ""
+    end
+
+    def generate_query_pages(generator)
+      @queries.each do |query|
+        $stderr.puts("Generating docs for #{query.path}")
+        html = render_with_layout(generator, :query, {query: query})
+        generator.write_file(self, query.output_filename, html)
+      end
+    end
+
+  end
+end

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

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

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

@@ -2,7 +2,7 @@
 <html class="h-100">
   <head>
     <meta http-equiv="content-type" content="text/html; charset=UTF-8">
-    <title><%= _title %></title>
+    <title><%= title %></title>
 
     <script src="jquery.js" type="text/javascript"></script>
 	  <script src="bootstrap.min.js" type="text/javascript"></script>
@@ -41,19 +41,19 @@
     <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>
+            <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 %>
+                <% 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| %>
+                <% if metadata["extra-files"] %>
+        		  	  <% metadata["extra-files"].each do |file| %>
                     <li class="nav-item">
                       <a class="nav-link" href="<%= file.gsub(".md", ".html") %>"><%= file.gsub(".md", "").capitalize %></a>
                     </li>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: overpass-doc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Leigh Dodds
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-18 00:00:00.000000000 Z
+date: 2021-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -108,6 +108,7 @@ files:
 - lib/overpass-doc/assets/util/simple-hint.js
 - lib/overpass-doc/assets/util/xml-hint.js
 - lib/overpass-doc/generator.rb
+- lib/overpass-doc/package.rb
 - lib/overpass-doc/query.rb
 - lib/overpass-doc/views/extra.erb
 - lib/overpass-doc/views/index.erb