[AURORA-1668] http://aurora.apache.org/documentation/latest/ is mainly broken for 0.13.0

• Type: Bug
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 0.14.0
• Component/s: Documentation
• Assignee: John Sirois
• Reporter: John Sirois
• Created: 16/Apr/16 16:25
• Updated: 10/Jun/16 13:07
• Resolved: 19/Apr/16 17:24

Description

The Rakefile for generating the site documentation assumes a single flat directory of markdown files, see line 104 below:

54	desc 'Fetch markdown from the source tree and generate docs for a specific git tag.'
55	task :generate_docs, [:title, :git_tag] do |t, args|
56	  if !args[:title] or !args[:git_tag]
57	    puts args, 'Usage: generate_docs[TITLE, GIT_TAG]'
58	    exit 1
59	  end
60	
61	  title = args[:title]
62	  git_tag = args[:git_tag]
63	
64	  puts "Generating docs from git tag #{git_tag} with title #{title}"
65	
66	  tmp_dir = File.join(File.dirname(__FILE__), 'tmp')
67	  #Rake::Task[:clean].invoke if File.exist?(tmp_dir)
68	
69	  FileUtils.mkdir_p(tmp_dir)
70	  
71	  zip_name = "#{git_tag}.zip"
72	  is_master = ['master', 'HEAD'].include? git_tag
73	  archive_root = if is_master then "aurora-#{git_tag}" else "aurora-rel-#{git_tag}" end
74	  archive_rel_url = if is_master then zip_name else "rel/#{zip_name}" end
75	
76	  Dir.chdir(tmp_dir) {
77	    if File.exist?(zip_name) and not is_master
78	      puts 'Skipping archive fetch'
79	    else
80	      puts "Fetching archive of #{git_tag}"
81	      system("wget https://github.com/apache/aurora/archive/#{archive_rel_url} -O #{zip_name}")
82	    end
83	    system("unzip -o #{zip_name} '#{archive_root}/docs/*'")
84	  }
85	
86	  docs_in_dir = File.join(tmp_dir, archive_root, 'docs')
87	  docs_out_dir = File.join('source', 'documentation', title)
88	  FileUtils.rm_f(docs_out_dir)
89	  FileUtils.mkdir_p(docs_out_dir)
90	
91	  FileUtils.cp_r(Dir.glob(File.join(docs_in_dir, '*')), docs_out_dir)
92	
93	  puts 'Translating documentation'
94	  Dir.chdir(docs_out_dir) {
95	    FileUtils.mv('README.md', 'index.html.md')
96	
97	    # Rename the contributing page to lower case.  This doesn't exist in all releases, so we
98	    # check first if it exists.
99	    contributing_doc = 'CONTRIBUTING.md'
100	    if File.exist?(contributing_doc)
101	      FileUtils.mv(contributing_doc, contributing_doc.downcase)
102	    end
103	
104	    Dir.glob('*.md').each { |doc|
105	      puts "working on: #{doc}"
106	
107	      # Hacks to make markdown intended for GitHub work.
108	      IO.write(doc, File.open(doc, :encoding => 'utf-8') { |f|
109	        f.read.
110	            # Rewrite links to '../CONTRIBUTING.md'.
111	            gsub(/\.\.\/CONTRIBUTING\.md/, 'contributing/').
112	            # Rewrite links pointing to source files in the repository.
113	            gsub(/\]\(\.\.\/([^\)]+\))/, '](https://github.com/apache/aurora/blob/#{git_tag}/\1)').
114	            # Remove .md extension in links.
115	            gsub(/\(([A-Za-z0-9-]+)\.md(#[^\)]+)?\)/, "(/documentation/#{title}/\\1/\\2)").
116	            # Fix anchor links and names, which GitHub prefixes with 'user-content-'
117	            # See AURORA-726.
118	            gsub(/#user-content\-/, '#').
119	            # Fix image links.  This is necessary because middleman turns each markdown page
120	            # into a directory name.  During this process, relative image tags in HTML are not
121	            # adjusted accordingly.
122	            gsub(/img src="images\//, "img src=\"/documentation/#{title}/images/")
123	      })
124	    }
125	  }
126	end

As a result most of the documentation is left untranslated.

The Rakefile will need a re-work to handle a general directory tree of markdown files to process.

Issue Links

• is duplicated by: AURORA-1671 All links in the documentation page are broken
• relates to: AURORA-1673 Links going out from http://aurora.apache.org/documentation/0.13.0/ 404