Merge pull request #541 from atom/api-docs

Add Atom's API docs to the Flight Manual

.gitignore

@@ -16,3 +16,4 @@ atom.epub
 atom-kf8.epub
 atom.mobi
 /images/
+content/api

.node-version

@@ -0,0 +1 @@
+8.16.0

Gemfile

@@ -4,6 +4,7 @@ ruby '2.4.2'
 # essential
 gem 'nanoc', '~> 4.7'
 gem 'nanoc-conref-fs', '~> 0.7'
+gem 'nanoc-redirector', '~> 0.2'
 
 # rendering
 gem 'nanoc-html-pipeline', '~> 0.3'
@@ -12,6 +13,8 @@ gem 'html-pipeline-rouge_filter', '~> 1.0'
 gem 'extended-markdown-filter', '~> 0.4'
 gem 'html-pipeline-asciidoc_filter', '~> 1.5'
 gem 'github-markdown', '~> 0.6.9'
+gem 'kramdown'
+gem 'kramdown-parser-gfm'
 
 gem 'activesupport', '~> 4.2'
 gem 'rake'

Gemfile.lock

@@ -52,6 +52,9 @@ GEM
       yell (~> 2.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
+    kramdown (2.1.0)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     liquid (4.0.0)
     mercenary (0.3.6)
     method_source (0.9.0)
@@ -75,6 +78,8 @@ GEM
     nanoc-html-pipeline (0.3.5)
       html-pipeline (~> 2.0)
       nanoc (>= 3.1, < 5.0)
+    nanoc-redirector (0.3.0)
+      nanoc (~> 4.9.0)
     nokogiri (1.8.4)
       mini_portile2 (~> 2.3.0)
     parallel (1.12.1)
@@ -109,9 +114,12 @@ DEPENDENCIES
   html-pipeline-asciidoc_filter (~> 1.5)
   html-pipeline-rouge_filter (~> 1.0)
   html-proofer (~> 3.7)
+  kramdown
+  kramdown-parser-gfm
   nanoc (~> 4.7)
   nanoc-conref-fs (~> 0.7)
   nanoc-html-pipeline (~> 0.3)
+  nanoc-redirector (~> 0.2)
   pry
   pry-coolline
   rake
@@ -120,4 +128,4 @@ RUBY VERSION
    ruby 2.4.2p198
 
 BUNDLED WITH
-   1.16.3
+   2.0.2

Rakefile

@@ -1,8 +1,15 @@
 require "find"
+require 'fileutils'
+require 'json'
 require 'open3'
+require 'open-uri'
 
 task :default => [:test]
 
+task :clean_api do
+  FileUtils.rm_rf('content/api')
+end
+
 desc "Remove the tmp dir"
 task :remove_tmp_dir do
   FileUtils.rm_r('tmp') if File.exist?('tmp')
@@ -31,8 +38,9 @@ task :run_proofer do
   # Ignore platform switcher hash URLs
   platform_hash_urls = ['#platform-mac', '#platform-windows', '#platform-linux', '#platform-all']
   HTMLProofer.check_directory("./output", {
+    :file_ignore => [%r(/output/api/)],
     :url_ignore => platform_hash_urls,
-    :typhoeus => { :ssl_verifypeer => false }
+    :typhoeus => { :ssl_verifypeer => false },
   }).run
 end
 

Rules

@@ -1,6 +1,28 @@
 #!/usr/bin/env ruby
 
 require 'extended-markdown-filter'
+require 'nanoc-redirector'
+require_relative 'lib/filters/api_json_filter'
+require_relative 'lib/redirects'
+
+preprocess do
+  versions = @items.find_all('/api/*/*.json').map { |item| item.identifier.to_s.split('/')[2] }.uniq
+  versions.each do |version|
+    json_items_for_version = @items.find_all("/api/#{version}/*.json")
+    class_names_for_version = json_items_for_version.map { |item| File.basename(item.identifier, '.json') }
+    first_class_name_for_version = class_names_for_version.sort.first
+    create_item_with_redirect source: "/api/#{version}/index.md", destination: "/api/#{version}/#{first_class_name_for_version}"
+
+    @items.create('', {:api_version => version.tr('v', '')}, "/search/#{version}.json")
+  end
+
+  create_item_with_redirect source: '/api/index.md', destination: '/api/latest'
+  create_item_with_redirect source: '/api/latest.md', destination: "/api/v#{latest_atom_version_number}"
+end
+
+compile '/api/**/*.md' do
+  filter :redirect_to, { :redirect_to => @item[:redirect_to] }
+end
 
 compile '/index.html' do
   filter :erb
@@ -28,13 +50,24 @@ compile '**/*.md' do
   layout '/article.html'
 end
 
+compile '/api/**/*.json' do
+  class_name = File.basename(item.identifier.without_ext)
+  version = File.basename(File.dirname(item.identifier))
+
+  filter :api_json, class_name: class_name, version: version
+  filter :erb
+  layout '/api-class.html', :locals => { :version => version.tr('v', '') }
+end
+
 compile '/search.html' do
   filter :erb
   layout '/toc.html'
 end
 
-compile '/search.json' do
+compile '/search/*.json' do
   filter :erb
+  layout '/search.json'
+  write item.identifier
 end
 
 passthrough '/**/*.jpg'
@@ -43,10 +76,6 @@ passthrough '/**/*.png'
 passthrough '/**/*.gif'
 passthrough '/CNAME'
 
-route '/search.json' do
-  '/search.json'
-end
-
 route '**/*' do
   if item.binary?
     item.identifier.chop + (item[:extension] ? '.' + item[:extension] : '')

assets/javascripts/api-docs.js

@@ -0,0 +1,50 @@
+(function() {
+  if (isApiDocsPage()) {
+    $(document).on("click", ".js-api-name", function(e) {
+      e.preventDefault();
+      toggleApiEntry($(this).attr("href"));
+      return false;
+    });
+
+    $(document).ready(function() {
+      if (window.location.hash) {
+        toggleApiEntry(window.location.hash);
+      }
+
+      $("#documents-search-versions").change(function() {
+        const components = window.location.pathname.split("/");
+        if (!components[components.length - 1]) {
+          // Pop trailing slash off
+          components.pop();
+        }
+        const page = components.pop();
+        const version = this.value;
+        const { hash } = window.location;
+        window.location.replace(`/api/v${version}/${page}${hash}`);
+      });
+    });
+
+    $(window).on("hashchange", function() {
+      toggleApiEntry(window.location.hash);
+    });
+  }
+
+  function toggleApiEntry(apiEntryId) {
+    const entry = $(apiEntryId);
+    const extendedContainer = entry.parents(".extended-methods-container");
+    if (extendedContainer.length) {
+      extendedContainer.addClass("show");
+    }
+
+    if (entry.hasClass("expanded")) {
+      entry.removeClass("expanded");
+    } else {
+      entry.addClass("expanded");
+      window.history.replaceState("", "", apiEntryId); // update url hash w/o adding history
+    }
+  }
+
+  function isApiDocsPage() {
+    return window.location.pathname.startsWith("/api/");
+  }
+})();