MxW_Addon/Libraries/oUF/utils/docs

#!/usr/bin/env lua
-- docs
-- oUF documentation generator
--
-- This is really just a quick and dirty way of generating documentation for
-- oUF[1]. The syntax is inspired by TomDoc[2], but a lot of the non-oUF and
-- non-Lua things aren't implemented.
--
-- Why implement my own documentation generator?
-- It was mainly done because oUF is kind-of special, but also because the
-- available alternatives aren't good enough or have issues I can't workaround.
--
-- Things that need fixing:
--  - No highlighting of Lua code.
--  - Doesn't validate that comments are documentation strings.
--  - Doesn't parse its own documentation header.
--  - Close to zero error handling.
--
-- Usage
--
-- docs [docs path] [file...]
--
-- Links
--
-- [1] https://github.com/haste/oUF
-- [2] http://tomdoc.org/

local out
local lines

local tisf = function(fmt, ...)
	table.insert(out, fmt:format(...))
end

local trim = function(str)
	return str:match('^()%s*$') and '' or str:match('^%s*(.*%S)')
end

local findNextEmpty = function(start, stop)
	for i=start, stop or #lines do
		if(lines[i] == '') then
			return i
		end
	end
end

local findNextHeader = function(offest)
	for i=offest, #lines do
		local pre, header, post = unpack(lines, i, i + 2)
		-- Single lines without punctuation are headers.
		if(pre == '' and post == '' and not header:match'%.') then
			return i + 1
		end
	end
end

local findNextArguent = function(start, stop, padding, pattern)
	for i=start, stop do
		local match, pad = lines[i]:match(pattern)
		if(match and pad == padding) then
			return i
		end
	end
end

local replaceMarkup = function(str)
	return str
	-- `in-line code` to <code>in-line code</code>
	:gsub('`([^`]+)`', '<code>%1</code>')
	-- [Link](http://example.com) to <a href="http://example.com">Link</a>
	:gsub('%[([^%]]+)%]%(([^)]+)%)', '<a href="%2">%1</a>')
end

local handleArguments = function(start, stop, pattern)
	tisf('<dl>')
	repeat
		-- Tear out the argument name and offset of where the description begins.
		local def, padding, offset = lines[start]:match(pattern)
		tisf('<dt>%s</dt>', def)

		-- Insert the first line of the description.
		tisf('<dd>')
		tisf(lines[start]:sub(offset))

		-- Find the next argument in the list or continue to the end of the
		-- current section.
		local nextarg = findNextArguent(start + 1, stop, padding, pattern)
		nextarg = (nextarg or stop + 1) - 1
		for i=start + 1, nextarg do
			tisf(trim(lines[i]))
		end
		tisf('</dd>')

		start = nextarg + 1
	until start > stop
	tisf('</dl>')
end

local handleExamples = function(start, stop)
	-- An extra line gets added if we don't do this.
	tisf('<pre><code>%s', lines[start]:sub(3))
	for i=start + 1, stop  do
		tisf(lines[i]:sub(3))
	end
	tisf('</code></pre>')
end

local handleParagraph = function(start, stop)
	tisf('<p>')
	for i=start, stop do
		tisf(trim(lines[i]))
	end
	tisf('</p>')
end

local handleSection = function(start, stop)
	while(start) do
		-- Find the next empty line or continue until the end of the section.
		-- findNextEmpty() returns the position of the empty line, so we need to
		-- subtract one from it.
		local nextEmpty = findNextEmpty(start + 1, stop)
		if(nextEmpty) then
			nextEmpty = nextEmpty - 1
		else
			nextEmpty = stop
		end

		local line = lines[start]
		if(not line) then
			return
		elseif(line:match('^%S+%s*%- ')) then
			handleArguments(start, nextEmpty, '(%S+)%s*()%- ()')
		elseif(line:sub(1, 2) == '  ') then
			handleExamples(start, nextEmpty)
		else
			handleParagraph(start, nextEmpty)
		end

		start = findNextEmpty(nextEmpty, stop)
		if(start) then start = start + 1 end
	end
end

local generateDocs = function(str, level)
	lines = {}
	out = {}

	for line in str:gmatch('([^\n]*)\n') do
		table.insert(lines, line:gsub('\t*', ''):sub(2))
	end

	-- The first line is always the main header.
	tisf('<h%d>%s</h%d>', level, lines[1], level)

	-- Then comes the main description.
	local offset = findNextHeader(1)

	-- Continue until two lines before the header or to the end of the comment.
	if(offset) then
		offset = offset - 2
	else
		offset = #lines
	end

	local init = findNextEmpty(1) + 1
	if(init > offset) then
		init = 2
	end

	handleSection(init, offset)

	while(true) do
		offset = findNextHeader(offset)
		if(not offset) then break end

		-- Every section has a header.
		tisf('<h%d>%s</h%d>', level + 1, lines[offset], level + 1)

		-- Find out the size of the section.
		local start = findNextEmpty(offset) + 1
		if(not lines[start]) then
			-- There's no section here, only a headline.
			break
		end

		local stop
		local nextHeader = findNextHeader(start)
		if(nextHeader) then
			stop = nextHeader - 2
		else
			local nextEmpty = findNextEmpty(start)
			if(nextEmpty) then
				stop = nextEmpty - 1
			else
				stop = #lines
			end
		end

		handleSection(start, stop)
		offset = stop + 1
	end

	return table.concat(out, '\n')
end

local handleFile = function(path)
	local file = io.open(path, 'r')
	local content = file:read'*a'
	file:close()

	local out = {}
	local init = 1
	repeat
		local _, comStart, depth = content:find('%-%-%[(=*)%[ ', init)
		if(comStart) then
			local comEnd = content:find('%]' .. depth .. '%]', comStart)
			local comment = content:sub(comStart, comEnd - 1)

			-- Convert markup to html.
			comment = replaceMarkup(comment)

			-- The first comment uses h1 and h2, while the subsequent ones uses h3
			-- and h4.
			local level = init == 1 and 1 or 3
			table.insert(out, generateDocs(comment, init == 1 and 1 or 3))

			init = comEnd
		end
	until not comStart

	return table.concat(out, '\n')
end

local destination = (...)
for i=2, select('#', ...) do
	local file = select(i, ...)
	local path, filename = file:match('(.+)/(.+)$')

	if(path:sub(1,3) == '../') then
		path = path:sub(4)
	end

	if(#path == 0) then path = nil end
	filename = filename:gsub('lua', 'html')

	local doc = handleFile(file)
	if(doc) then
		local dfPath = string.format('%s/%s', destination, path or '')
		os.execute(string.format('mkdir -p %s', dfPath))
		local docFile = io.open(string.format('%s/%s', dfPath, filename), 'w+')
		docFile:write(doc)
		docFile:close()
	end
end