overpass-doc 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: '09dc2dab218ef799c024d923e6892bed2cb74be7c557b35b9e948cfe7782c514'
4
- data.tar.gz: d5e31bd7a8734a52c00fe9403f06482ab0ce813a0e90f8d80c5064d2c8e0e5ad
3
+ metadata.gz: 9fe57639d0bde35c080d670d1cf3e3f554908ba18722a4e1724f1c2ca225899d
4
+ data.tar.gz: cb2986b10059b85fc5b3c89c786b19ce7f3df406596b151d005f4bd23245f21c
5
5
  SHA512:
6
- metadata.gz: 72df74a6ce87ac2f9dd53f9599322f43ebf0e00d7f4618d0734f664c9c5425e9553cee09b74699d4d8cf0d42a1812b75c79bb73760b73257d3349fd5464edc69
7
- data.tar.gz: 86398341c02b2bf7d137b10bb085710ddc3dd2acd17a47357b3ae55a80d0652212dffb19da24b18547244d4a2c38c716bada6b156fe49b7b834366a4bcf9747f
6
+ metadata.gz: 579de47255bdd080218e1028594ea92f7656cd96ad9ff26e56097c23ea6d79218437c69d7eb761cea168caeec6255935bf1ee696e367aaa7dec02d2fa0dc4d44
7
+ data.tar.gz: 1d9291ccd32817d62e97a887b856188e9cfda505f6d242f1a8f92f7772066cd7420c903523f997c11155ee72e2f3a7c2cc3688bfaa5cecb203c44c03dc731b77
data/README.md CHANGED
@@ -1 +1,195 @@
1
- # Generate HTML documentation from Overpass queries
1
+ # Generate HTML documentation for OSM Overpass queries
2
+
3
+ `overpass-doc` provides a simple tool for generating browsable HTML documentation
4
+ from Overpass queries.
5
+
6
+ It's intended to support people in producing tutorials and training material
7
+ to help people learn how to query OpenStreetmap. It may also be helpful to local
8
+ communities or projects that regularly need to share and run queries. For example to
9
+ help monitor changes in their area, or identify mapping tasks.
10
+
11
+ ## Documenting Overpass queries
12
+
13
+ `overpass-doc` supports markup for documenting Overpass QL queries, as well as a
14
+ package metadata for a collection of queries.
15
+
16
+ These features are described in the next sections.
17
+
18
+ ### Overpass QL Documentation Extensions
19
+
20
+ `overpass-doc` processes your Overpass queries, saved as text files with a `.op` extension.
21
+
22
+ It then looks for a comment at the top of the query. Like Javadoc, rdoc and
23
+ similar tools, the content of those comments are used to provide metadata
24
+
25
+ All simple documentation lines at the start of a query will be treated as its description. E.g:
26
+
27
+ ```
28
+ /*
29
+ This is a description
30
+ of my query. It has multiple
31
+ lines
32
+ */
33
+ ```
34
+
35
+ Special tag can be used to specify other metadata, such as the title of a query:
36
+
37
+ ```
38
+ /*
39
+ This is a description
40
+ of my query. It has multiple
41
+ lines
42
+ @title This is the title
43
+ */
44
+ ```
45
+
46
+ The full list of supported tags is:
47
+
48
+ * `@title`: should have a single value. Last title tag wins
49
+ * `@author`: author(s) of the query.
50
+ * `@see`: add one or more links
51
+ * `@tags`: add a tag to a query. Multiple values
52
+
53
+ Here's an example that uses all these:
54
+
55
+ ```
56
+ /*
57
+ Specifies a bounding box to query for glacier data in a specific area of
58
+ Switzerland.
59
+
60
+ @title Extract glacier features as a specific location
61
+ @author Leigh Dodds
62
+ @see https://en.wikipedia.org/wiki/Upper_Grindelwald_Glacier
63
+ @tags glacier
64
+ */
65
+ [out:json][timeout:25][bbox:46.5914,8.0828,46.6301, 8.1674];
66
+ // gather results
67
+ (
68
+ // query part for: “natural=glacier”
69
+ node["natural"="glacier"];
70
+ way["natural"="glacier"];
71
+ relation["natural"="glacier"];
72
+ );
73
+ // print results
74
+ out body;
75
+ >;
76
+ out skel qt;
77
+ ```
78
+
79
+ The query description can be written in [Markdown](http://daringfireball.net/projects/markdown/). So
80
+ you can include embedded markup, e.g. links, that help to further document a query.
81
+
82
+ ### Overview Documentation
83
+
84
+ When processing a directory of queries, `overpass-doc` will automatically look for a file called
85
+ `overview.md`. If found, this file will be automatically parsed as Markdown and its contents included
86
+ in an Overview section on the homepage of the documentation.
87
+
88
+ While the `description` in the `package.json` file is intended to provide a one line summary of the
89
+ package, the `overview.md` file is intended to provide a more detailed introduction. Both are optional,
90
+ so authors can choose which approach they prefer.
91
+
92
+ ### Package Metadata
93
+
94
+ `overpass-doc` considers a directory of queries to be a _package_. Metadata that describes a package
95
+ and how its documentation should be generated is provided by a valid JSON file called `package.json` which
96
+ is found in the same directory.
97
+
98
+ The following example of a package.json file shows how to provide a title and a short description
99
+ of a package of files. The title and description will automatically be injected into the documentation.
100
+
101
+ ```
102
+ {
103
+ "title": "Sample OSM Queries",
104
+ "description": "A useful selection of queries for beginners"
105
+ }
106
+ ```
107
+
108
+ It is common for a collection of queries to be written by the same person, be tagged in the same
109
+ way, or be useful against the same collection of endpoints. Rather than repeatedly apply the
110
+ `@author`, `@tags` and `@endpoint` annotations to all queries in a package, default values can be
111
+ specified in the `package.json` file.
112
+
113
+ The following example shows how to do this:
114
+
115
+ ```
116
+ {
117
+ "title": "Sample OSM Queries",
118
+ "description": "A useful selection of queries for beginners"
119
+ "author": ["Leigh Dodds"],
120
+ }
121
+ ```
122
+
123
+ Note that because `@author`, `@tags` and `@see` are all multi-valued annotations, their values
124
+ must be specified as a JSON array.
125
+
126
+ The `package.json` file can also be used to indicate that extra files in the query directory should be
127
+ processed and included in the documentation. E.g.:
128
+
129
+ ```
130
+ {
131
+ "title": "Sample OSM Queries",
132
+ "description": "A useful selection of queries for beginners"
133
+ "extra-files": ["more-info.md"]
134
+ }
135
+ ```
136
+
137
+ This will trigger `overpass-doc` to process the `more-info.md` file as Markdown, converting it to
138
+ `more-info.html` which is added to the output directory. A link to `more-info` will be automatically
139
+ added to the header navigation
140
+
141
+ ## Example
142
+
143
+ Here's [some example output](https://ldodds.github.io/osm-queries/) using the example queries included in the project.
144
+
145
+ ## Installation
146
+
147
+ `overpass-doc` is available as a gem:
148
+
149
+ gem install overpass-doc
150
+
151
+ ### Manual Install
152
+
153
+ You'll need to make sure you have the following installed:
154
+
155
+ * Ruby 2.5.0+
156
+ * RubyGems
157
+ * Bundler
158
+ * Rake
159
+
160
+ Once you have those installed, clone the repository and run the provided rake targets to build and install the gem
161
+ locally:
162
+
163
+ git clone https://github.com/ldodds/overpass-doc.git
164
+ cd overpass-doc
165
+
166
+ The code uses two gems which you'll need to have installed: JSON and [Redcarpet](https://github.com/vmg/redcarpet):
167
+
168
+ bundle install
169
+
170
+ Once installed you should be able to run the `bin/overpass-doc` command-line tool.
171
+
172
+ ## Usage
173
+
174
+ _Note: the command-line syntax is likely to change in future. E.g. to add more options and/or other commands_
175
+
176
+ This takes two parameters:
177
+
178
+ * The input directory. The tool will process all `.op` files in that directory
179
+ * The output directory. All HTML output and required assets will be placed here
180
+
181
+ The output directory is optional. If not specified it will create a directory called
182
+ `overpass-doc` in the current directory.
183
+
184
+ E.g. you can run:
185
+
186
+ overpass-doc queries pages
187
+
188
+ This will generate documentation from the bundled examples and place it into the specified
189
+ directory.
190
+
191
+ ## License
192
+
193
+ This work is hereby released into the Public Domain.
194
+
195
+ 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 CHANGED
@@ -6,4 +6,5 @@ require 'fileutils'
6
6
  require 'redcarpet'
7
7
 
8
8
  require 'overpass-doc/query'
9
+ require 'overpass-doc/package'
9
10
  require 'overpass-doc/generator'
@@ -9,38 +9,31 @@ module OverpassDoc
9
9
  @output_dir = output_dir
10
10
  @asset_dir = asset_dir || File.join( File.dirname( __FILE__ ) , "assets")
11
11
  @view_dir = view_dir || File.join( File.dirname( __FILE__ ) , "views")
12
- @package = parse_package()
13
- @queries = parse_queries()
12
+ @package = OverpassDoc::Package.new(@dir)
13
+ @templates = {}
14
14
  end
15
15
 
16
- def read_template(name)
17
- File.read(File.join(@view_dir, "#{name}.erb"))
16
+ def run
17
+ copy_assets
18
+ @package.generate(self)
19
+ rescue => e
20
+ puts e
21
+ puts e.backtrace
18
22
  end
19
23
 
20
- def parse_package()
21
- package = File.join(@dir, "package.json")
22
- if File.exists?(package)
23
- return JSON.load( File.open(package) )
24
- end
25
- Hash.new
24
+ def read_template(name)
25
+ return @templates[name] if @templates[name]
26
+ @templates[name] = File.read(File.join(@view_dir, "#{name}.erb"))
27
+ return @templates[name]
26
28
  end
27
29
 
28
- def parse_queries()
29
- queries = []
30
- Dir.glob("#{@dir}/*.op") do |file|
31
- content = File.read(file)
32
- path = file.gsub("#{@dir}/", "")
33
- queries << OverpassDoc::Query.new(path, content, @package)
30
+ def write_file(package, filename, content)
31
+ if File.dirname(filename) != "."
32
+ FileUtils.mkdir_p File.join(@output_dir, File.dirname(filename))
33
+ end
34
+ File.open(File.join(@output_dir, filename), "w") do |f|
35
+ f.puts(content)
34
36
  end
35
- queries.sort! {|x,y| x.title <=> y.title }
36
- queries
37
- end
38
-
39
- def run()
40
- copy_assets()
41
- generate_index()
42
- generate_query_pages()
43
- copy_extra_files()
44
37
  end
45
38
 
46
39
  def copy_assets(asset_dir=@asset_dir)
@@ -51,72 +44,5 @@ module OverpassDoc
51
44
  FileUtils.cp_r( "#{@asset_dir}/.", @output_dir )
52
45
  end
53
46
 
54
- def copy_extra_files()
55
- @package["extra-files"].each do |file|
56
- markup = File.read( File.join(@dir, file) )
57
- renderer = Redcarpet::Render::HTML.new({})
58
- markdown = Redcarpet::Markdown.new(renderer, {})
59
- template = ERB.new( read_template(:extra) )
60
- _content = markdown.render(markup)
61
- html = layout do
62
- b = binding
63
- template.result(b)
64
- end
65
- file = File.join(@output_dir, file.gsub(".md", ".html"))
66
- File.open(file, "w") do |f|
67
- f.puts html
68
- end
69
- end if @package["extra-files"]
70
- end
71
-
72
- def get_overview()
73
- overview = File.join(@dir, "overview.md")
74
- if File.exists?( overview )
75
- markup = File.read( overview )
76
- renderer = Redcarpet::Render::HTML.new({})
77
- markdown = Redcarpet::Markdown.new(renderer, {})
78
- return markdown.render(markup)
79
- end
80
- nil
81
- end
82
-
83
- def generate_index()
84
- $stderr.puts("Generating index.html");
85
- _title = @package["title"] || "Overpass Query Documentation"
86
- _overview = get_overview()
87
- _description = @package["description"] || ""
88
- template = ERB.new( read_template(:index) )
89
- html = layout do
90
- b = binding
91
- template.result(b)
92
- end
93
- File.open(File.join(@output_dir, "index.html"), "w") do |f|
94
- f.puts(html)
95
- end
96
- end
97
-
98
- def layout
99
- b = binding
100
- _title = @package["title"] || "Overpass Query Documentation"
101
- _overview = get_overview()
102
- ERB.new( read_template(:layout) ).result(b)
103
- end
104
-
105
- def generate_query_pages()
106
- template = ERB.new( read_template(:query) )
107
- @queries.each do |query|
108
- $stderr.puts("Generating docs for #{query.path}")
109
- File.open( File.join(@output_dir, query.output_filename), "w" ) do |f|
110
- b = binding
111
- _title = @package["title"] || "Overpass Query Documentation"
112
- _overview = get_overview()
113
- html = layout do
114
- template.result(b)
115
- end
116
- f.puts( html )
117
- end
118
- end
119
- end
120
-
121
47
  end
122
48
  end
@@ -0,0 +1,111 @@
1
+ module OverpassDoc
2
+ #A directory containing a package.json, query files and supporting assets
3
+ class Package
4
+ attr_reader :dir, :queries, :metadata
5
+
6
+ def initialize(src_dir)
7
+ @dir = src_dir
8
+ @metadata = parse_metadata()
9
+ @queries = parse_queries()
10
+ end
11
+
12
+ def generate(generator)
13
+ generate_index(generator)
14
+ generate_query_pages(generator)
15
+ copy_extra_files(generator)
16
+ end
17
+
18
+ private
19
+
20
+ def parse_metadata()
21
+ package = File.join(@dir, "package.json")
22
+ if File.exists?(package)
23
+ return JSON.load( File.open(package) )
24
+ end
25
+ Hash.new
26
+ end
27
+
28
+ def parse_queries()
29
+ queries = []
30
+ Dir.glob("#{@dir}/**/*.op") do |file|
31
+ content = File.read(file)
32
+ path = file.gsub("#{@dir}/", "")
33
+ queries << OverpassDoc::Query.new(path, content, @metadata)
34
+ end
35
+ queries.sort! {|x,y| x.title <=> y.title }
36
+ queries
37
+ end
38
+
39
+ def copy_extra_files(generator)
40
+ @metadata["extra-files"].each do |file|
41
+ markup = File.read( File.join(@dir, file) )
42
+ _content = render_markdown(markup)
43
+ template = ERB.new( generator.read_template(:extra) )
44
+ html = layout(generator) do
45
+ b = binding
46
+ template.result(b)
47
+ end
48
+ filename = file.gsub(".md", ".html")
49
+ generator.write_file(self, filename, html)
50
+ end if @metadata["extra-files"]
51
+ end
52
+
53
+ #available in template
54
+ def overview
55
+ return @overview if @overview
56
+ overview = File.join(@dir, "overview.md")
57
+ if File.exists?( overview )
58
+ markup = File.read( overview )
59
+ @overview = render_markdown(markup)
60
+ return @overview
61
+ end
62
+ nil
63
+ end
64
+
65
+ def generate_index(generator)
66
+ $stderr.puts("Generating index.html")
67
+ generator.write_file(self, "index.html", render_with_layout(generator, :index))
68
+ end
69
+
70
+ def render_markdown(src)
71
+ renderer = Redcarpet::Render::HTML.new({})
72
+ markdown = Redcarpet::Markdown.new(renderer, {})
73
+ markdown.render(src)
74
+ end
75
+
76
+ def render_with_layout(generator, template, variables={})
77
+ template = ERB.new( generator.read_template(template) )
78
+ b = binding
79
+ variables.each do |key, value|
80
+ b.local_variable_set(key, value)
81
+ end
82
+ html = layout(generator) do
83
+ template.result(b)
84
+ end
85
+ return html
86
+ end
87
+
88
+ def layout(generator)
89
+ b = binding
90
+ ERB.new( generator.read_template(:layout) ).result(b)
91
+ end
92
+
93
+ #available in template
94
+ def title
95
+ @metadata["title"] || "Overpass Query Documentation"
96
+ end
97
+
98
+ def description
99
+ @metadata["description"] || ""
100
+ end
101
+
102
+ def generate_query_pages(generator)
103
+ @queries.each do |query|
104
+ $stderr.puts("Generating docs for #{query.path}")
105
+ html = render_with_layout(generator, :query, {query: query})
106
+ generator.write_file(self, query.output_filename, html)
107
+ end
108
+ end
109
+
110
+ end
111
+ end
@@ -1,14 +1,14 @@
1
1
  <div class="container">
2
2
  <div class="bg-light p-5 rounded">
3
- <h1><%= _title %></h1>
4
- <p class="lead"><%= _description %></p>
3
+ <h1><%= title %></h1>
4
+ <p class="lead"><%= description %></p>
5
5
  </div>
6
6
 
7
- <% if _overview %>
7
+ <% if overview %>
8
8
  <div class="row">
9
9
  <div class="col">
10
10
  <h3 id="overview">Overview</h3>
11
- <%= _overview %>
11
+ <%= overview %>
12
12
  </div>
13
13
  </div>
14
14
  <% end %>
@@ -16,7 +16,7 @@
16
16
  <div class="row">
17
17
  <div class="col">
18
18
  <h3>Queries</h3>
19
- <p>This set of documentation covers <strong><%= @queries.size %></strong> queries</p>
19
+ <p>This set of documentation covers <strong><%= queries.size %></strong> queries</p>
20
20
  <table class="table table-hover">
21
21
  <thead>
22
22
  <tr>
@@ -24,7 +24,7 @@
24
24
  </tr>
25
25
  </thead>
26
26
  <tbody>
27
- <% @queries.each do |query| %>
27
+ <% queries.each do |query| %>
28
28
  <tr>
29
29
  <td><a href="<%= query.output_filename %>"><%= query.title %></a></td><td><code><%= query.path %></code></td>
30
30
  </tr>
@@ -2,7 +2,7 @@
2
2
  <html class="h-100">
3
3
  <head>
4
4
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5
- <title><%= _title %></title>
5
+ <title><%= title %></title>
6
6
 
7
7
  <script src="jquery.js" type="text/javascript"></script>
8
8
  <script src="bootstrap.min.js" type="text/javascript"></script>
@@ -41,19 +41,19 @@
41
41
  <header>
42
42
  <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark">
43
43
  <div class="container-fluid">
44
- <a class="navbar-brand" href="index.html"><%= _title %></a>
44
+ <a class="navbar-brand" href="index.html"><%= title %></a>
45
45
  <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
46
46
  <span class="navbar-toggler-icon"></span>
47
47
  </button>
48
48
  <div class="collapse navbar-collapse" id="navbarCollapse">
49
49
  <ul class="navbar-nav me-auto mb-2 mb-md-0">
50
- <% if _overview %>
50
+ <% if overview %>
51
51
  <li class="nav-item">
52
52
  <a class="nav-link active" aria-current="page" href="index.html#overview">Overview</a>
53
53
  </li>
54
54
  <% end %>
55
- <% if @package["extra-files"] %>
56
- <% @package["extra-files"].each do |file| %>
55
+ <% if metadata["extra-files"] %>
56
+ <% metadata["extra-files"].each do |file| %>
57
57
  <li class="nav-item">
58
58
  <a class="nav-link" href="<%= file.gsub(".md", ".html") %>"><%= file.gsub(".md", "").capitalize %></a>
59
59
  </li>
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: overpass-doc
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 0.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Leigh Dodds
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-02-18 00:00:00.000000000 Z
11
+ date: 2021-02-19 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: json
@@ -108,6 +108,7 @@ files:
108
108
  - lib/overpass-doc/assets/util/simple-hint.js
109
109
  - lib/overpass-doc/assets/util/xml-hint.js
110
110
  - lib/overpass-doc/generator.rb
111
+ - lib/overpass-doc/package.rb
111
112
  - lib/overpass-doc/query.rb
112
113
  - lib/overpass-doc/views/extra.erb
113
114
  - lib/overpass-doc/views/index.erb