From 375d0e6b94781156a76682d39b89db507b5d24cd Mon Sep 17 00:00:00 2001
From: mitchell <70453897+orbitalquark@users.noreply.github.com>
Date: Thu, 1 Oct 2020 16:43:14 -0400
Subject: Moved 'docs/markdowndoc.lua' into 'scripts/markdowndoc.lua'.
---
docs/markdowndoc.lua | 170 ------------------------------------------------
scripts/markdowndoc.lua | 170 ++++++++++++++++++++++++++++++++++++++++++++++++
src/Makefile | 2 +-
3 files changed, 171 insertions(+), 171 deletions(-)
delete mode 100644 docs/markdowndoc.lua
create mode 100644 scripts/markdowndoc.lua
diff --git a/docs/markdowndoc.lua b/docs/markdowndoc.lua
deleted file mode 100644
index eb2d9a2a..00000000
--- a/docs/markdowndoc.lua
+++ /dev/null
@@ -1,170 +0,0 @@
--- Copyright 2007-2020 Mitchell. See LICENSE.
-
--- Markdown doclet for Luadoc.
--- @usage luadoc -doclet path/to/markdowndoc [file(s)] > api.md
-local M = {}
-
-local TOC = '1. [%s](%s)\n'
-local MODULE = '\n## The `%s` Module\n'
-local FIELD = '\n#### `%s` %s\n\n'
-local FUNCTION = '\n#### `%s`(*%s*)\n\n'
-local FUNCTION_NO_PARAMS = '\n#### `%s`()\n\n'
-local DESCRIPTION = '%s\n\n'
-local LIST_TITLE = '%s:\n\n'
-local PARAM = '* *`%s`*: %s\n'
-local USAGE = '* `%s`\n'
-local RETURN = '* %s\n'
-local SEE = '* [`%s`](#%s)\n'
-local TABLE = '\n#### `%s`\n\n'
-local TFIELD = '* `%s`: %s\n'
-local titles = {
- [PARAM] = 'Parameters', [USAGE] = 'Usage', [RETURN] = 'Return',
- [SEE] = 'See also', [TFIELD] = 'Fields'
-}
-
--- Writes a LuaDoc description to the given file.
--- @param f The markdown file being written to.
--- @param description The description.
--- @param name The name of the module the description belongs to. Used for
--- headers in module descriptions.
-local function write_description(f, description, name)
- -- Substitute custom [`code`]() link convention with [`code`](#code) links.
- local self_link = '(%[`([^`(]+)%(?%)?`%])%(%)'
- description = description:gsub(self_link, function(link, id)
- return string.format('%s(#%s)', link, id:gsub(':', '.'))
- end)
- f:write(string.format(DESCRIPTION, description))
-end
-
--- Writes a LuaDoc list to the given file.
--- @param f The markdown file being written to.
--- @param fmt The format of a list item.
--- @param list The LuaDoc list.
--- @param name The name of the module the list belongs to. Used for @see.
-local function write_list(f, fmt, list, name)
- if not list or #list == 0 then return end
- if type(list) == 'string' then list = {list} end
- f:write(string.format(LIST_TITLE, titles[fmt]))
- for _, value in ipairs(list) do
- if fmt == SEE and name ~= '_G' then
- if not value:find('%.') then
- -- Prepend module name to identifier if necessary.
- value = name .. '.' .. value
- else
- -- TODO: cannot link to fields, functions, or tables in `_G`?
- value = value:gsub('^_G%.', '')
- end
- end
- f:write(string.format(fmt, value, value))
- end
- f:write('\n')
-end
-
--- Writes a LuaDoc hashmap to the given file.
--- @param f The markdown file being written to.
--- @param fmt The format of a hashmap item.
--- @param list The LuaDoc hashmap.
-local function write_hashmap(f, fmt, hashmap)
- if not hashmap or #hashmap == 0 then return end
- f:write(string.format(LIST_TITLE, titles[fmt]))
- for _, name in ipairs(hashmap) do
- f:write(string.format(fmt, name, hashmap[name] or ''))
- end
- f:write('\n')
-end
-
--- Called by LuaDoc to process a doc object.
--- @param doc The LuaDoc doc object.
-function M.start(doc)
- local modules, files = doc.modules, doc.files
- local f = io.stdout
- f:write('## Textadept API Documentation\n\n')
-
- -- Create the table of contents.
- for _, name in ipairs(modules) do
- f:write(string.format(TOC, name, '#' .. name))
- end
- f:write('\n')
-
- -- Create a map of doc objects to file names so their Markdown doc comments
- -- can be extracted.
- local filedocs = {}
- for _, name in ipairs(files) do filedocs[files[name].doc] = name end
-
- -- Loop over modules, writing the Markdown document to stdout.
- for _, name in ipairs(modules) do
- local module = modules[name]
-
- -- Write the header and description.
- f:write(string.format(MODULE, name, name))
- f:write('---\n\n')
- write_description(f, module.description, name)
-
- -- Write fields.
- if module.doc[1].class == 'module' then
- local fields = module.doc[1].field
- if fields and #fields > 0 then
- table.sort(fields)
- f:write('### Fields defined by `', name, '`\n\n')
- for _, field in ipairs(fields) do
- local type, description = fields[field]:match('^(%b())%s*(.+)$')
- if not field:find('%.') and name ~= '_G' then
- field = name .. '.' .. field -- absolute name
- else
- field = field:gsub('^_G%.', '') -- strip _G required for Luadoc
- end
- f:write(string.format(FIELD, field, field, type or ''))
- write_description(f, description or fields[field])
- end
- f:write('\n')
- end
- end
-
- -- Write functions.
- local funcs = module.functions
- if #funcs > 0 then
- f:write('### Functions defined by `', name, '`\n\n')
- for _, fname in ipairs(funcs) do
- local func = funcs[fname]
- local params = table.concat(func.param, ', '):gsub('_', '\\_')
- if not func.name:find('[%.:]') and name ~= '_G' then
- func.name = name .. '.' .. func.name -- absolute name
- end
- if params ~= '' then
- f:write(string.format(FUNCTION, func.name, func.name, params))
- else
- f:write(string.format(FUNCTION_NO_PARAMS, func.name, func.name))
- end
- write_description(f, func.description)
- write_hashmap(f, PARAM, func.param)
- write_list(f, USAGE, func.usage)
- write_list(f, RETURN, func.ret)
- write_list(f, SEE, func.see, name)
- end
- f:write('\n')
- end
-
- -- Write tables.
- local tables = module.tables
- if #tables > 0 then
- f:write('### Tables defined by `', name, '`\n\n')
- for _, tname in ipairs(tables) do
- local tbl = tables[tname]
- if not tbl.name:find('%.') and
- (name ~= '_G' or tbl.name == 'buffer' or tbl.name == 'view') then
- tbl.name = name .. '.' .. tbl.name -- absolute name
- elseif tbl.name ~= '_G.keys' and tbl.name ~= '_G.snippets' then
- tbl.name = tbl.name:gsub('^_G%.', '') -- strip _G required for Luadoc
- end
- f:write(string.format(TABLE, tbl.name, tbl.name))
- write_description(f, tbl.description)
- write_hashmap(f, TFIELD, tbl.field)
- write_list(f, USAGE, tbl.usage)
- write_list(f, SEE, tbl.see, name)
- end
- end
- f:write('---\n')
- end
-end
-
-return M
diff --git a/scripts/markdowndoc.lua b/scripts/markdowndoc.lua
new file mode 100644
index 00000000..eb2d9a2a
--- /dev/null
+++ b/scripts/markdowndoc.lua
@@ -0,0 +1,170 @@
+-- Copyright 2007-2020 Mitchell. See LICENSE.
+
+-- Markdown doclet for Luadoc.
+-- @usage luadoc -doclet path/to/markdowndoc [file(s)] > api.md
+local M = {}
+
+local TOC = '1. [%s](%s)\n'
+local MODULE = '\n## The `%s` Module\n'
+local FIELD = '\n#### `%s` %s\n\n'
+local FUNCTION = '\n#### `%s`(*%s*)\n\n'
+local FUNCTION_NO_PARAMS = '\n#### `%s`()\n\n'
+local DESCRIPTION = '%s\n\n'
+local LIST_TITLE = '%s:\n\n'
+local PARAM = '* *`%s`*: %s\n'
+local USAGE = '* `%s`\n'
+local RETURN = '* %s\n'
+local SEE = '* [`%s`](#%s)\n'
+local TABLE = '\n#### `%s`\n\n'
+local TFIELD = '* `%s`: %s\n'
+local titles = {
+ [PARAM] = 'Parameters', [USAGE] = 'Usage', [RETURN] = 'Return',
+ [SEE] = 'See also', [TFIELD] = 'Fields'
+}
+
+-- Writes a LuaDoc description to the given file.
+-- @param f The markdown file being written to.
+-- @param description The description.
+-- @param name The name of the module the description belongs to. Used for
+-- headers in module descriptions.
+local function write_description(f, description, name)
+ -- Substitute custom [`code`]() link convention with [`code`](#code) links.
+ local self_link = '(%[`([^`(]+)%(?%)?`%])%(%)'
+ description = description:gsub(self_link, function(link, id)
+ return string.format('%s(#%s)', link, id:gsub(':', '.'))
+ end)
+ f:write(string.format(DESCRIPTION, description))
+end
+
+-- Writes a LuaDoc list to the given file.
+-- @param f The markdown file being written to.
+-- @param fmt The format of a list item.
+-- @param list The LuaDoc list.
+-- @param name The name of the module the list belongs to. Used for @see.
+local function write_list(f, fmt, list, name)
+ if not list or #list == 0 then return end
+ if type(list) == 'string' then list = {list} end
+ f:write(string.format(LIST_TITLE, titles[fmt]))
+ for _, value in ipairs(list) do
+ if fmt == SEE and name ~= '_G' then
+ if not value:find('%.') then
+ -- Prepend module name to identifier if necessary.
+ value = name .. '.' .. value
+ else
+ -- TODO: cannot link to fields, functions, or tables in `_G`?
+ value = value:gsub('^_G%.', '')
+ end
+ end
+ f:write(string.format(fmt, value, value))
+ end
+ f:write('\n')
+end
+
+-- Writes a LuaDoc hashmap to the given file.
+-- @param f The markdown file being written to.
+-- @param fmt The format of a hashmap item.
+-- @param list The LuaDoc hashmap.
+local function write_hashmap(f, fmt, hashmap)
+ if not hashmap or #hashmap == 0 then return end
+ f:write(string.format(LIST_TITLE, titles[fmt]))
+ for _, name in ipairs(hashmap) do
+ f:write(string.format(fmt, name, hashmap[name] or ''))
+ end
+ f:write('\n')
+end
+
+-- Called by LuaDoc to process a doc object.
+-- @param doc The LuaDoc doc object.
+function M.start(doc)
+ local modules, files = doc.modules, doc.files
+ local f = io.stdout
+ f:write('## Textadept API Documentation\n\n')
+
+ -- Create the table of contents.
+ for _, name in ipairs(modules) do
+ f:write(string.format(TOC, name, '#' .. name))
+ end
+ f:write('\n')
+
+ -- Create a map of doc objects to file names so their Markdown doc comments
+ -- can be extracted.
+ local filedocs = {}
+ for _, name in ipairs(files) do filedocs[files[name].doc] = name end
+
+ -- Loop over modules, writing the Markdown document to stdout.
+ for _, name in ipairs(modules) do
+ local module = modules[name]
+
+ -- Write the header and description.
+ f:write(string.format(MODULE, name, name))
+ f:write('---\n\n')
+ write_description(f, module.description, name)
+
+ -- Write fields.
+ if module.doc[1].class == 'module' then
+ local fields = module.doc[1].field
+ if fields and #fields > 0 then
+ table.sort(fields)
+ f:write('### Fields defined by `', name, '`\n\n')
+ for _, field in ipairs(fields) do
+ local type, description = fields[field]:match('^(%b())%s*(.+)$')
+ if not field:find('%.') and name ~= '_G' then
+ field = name .. '.' .. field -- absolute name
+ else
+ field = field:gsub('^_G%.', '') -- strip _G required for Luadoc
+ end
+ f:write(string.format(FIELD, field, field, type or ''))
+ write_description(f, description or fields[field])
+ end
+ f:write('\n')
+ end
+ end
+
+ -- Write functions.
+ local funcs = module.functions
+ if #funcs > 0 then
+ f:write('### Functions defined by `', name, '`\n\n')
+ for _, fname in ipairs(funcs) do
+ local func = funcs[fname]
+ local params = table.concat(func.param, ', '):gsub('_', '\\_')
+ if not func.name:find('[%.:]') and name ~= '_G' then
+ func.name = name .. '.' .. func.name -- absolute name
+ end
+ if params ~= '' then
+ f:write(string.format(FUNCTION, func.name, func.name, params))
+ else
+ f:write(string.format(FUNCTION_NO_PARAMS, func.name, func.name))
+ end
+ write_description(f, func.description)
+ write_hashmap(f, PARAM, func.param)
+ write_list(f, USAGE, func.usage)
+ write_list(f, RETURN, func.ret)
+ write_list(f, SEE, func.see, name)
+ end
+ f:write('\n')
+ end
+
+ -- Write tables.
+ local tables = module.tables
+ if #tables > 0 then
+ f:write('### Tables defined by `', name, '`\n\n')
+ for _, tname in ipairs(tables) do
+ local tbl = tables[tname]
+ if not tbl.name:find('%.') and
+ (name ~= '_G' or tbl.name == 'buffer' or tbl.name == 'view') then
+ tbl.name = name .. '.' .. tbl.name -- absolute name
+ elseif tbl.name ~= '_G.keys' and tbl.name ~= '_G.snippets' then
+ tbl.name = tbl.name:gsub('^_G%.', '') -- strip _G required for Luadoc
+ end
+ f:write(string.format(TABLE, tbl.name, tbl.name))
+ write_description(f, tbl.description)
+ write_hashmap(f, TFIELD, tbl.field)
+ write_list(f, USAGE, tbl.usage)
+ write_list(f, SEE, tbl.see, name)
+ end
+ end
+ f:write('---\n')
+ end
+end
+
+return M
diff --git a/src/Makefile b/src/Makefile
index 548db452..ccd99a07 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -284,7 +284,7 @@ manual: ../docs/api.md $(wildcard ../docs/*.md) | ../docs/_layouts/default.html
"s/\(\# Textadept\).\+\?\(Manual\|API\)/\1 $(subst _, ,$(version)) \2/;" \
../docs/*.md
luadoc: ../core $(modules) ../lexers/lexer.lua | ../modules/lua/lua.luadoc
- cd ../docs && luadoc --doclet markdowndoc $^ > api.md
+ cd ../scripts && luadoc --doclet markdowndoc $^ > ../docs/api.md
cd ../modules && luadoc -d lua --doclet lua/tadoc $^ --ta-home=$(ta_home)
cd ../modules/lua && mv tags ta_tags && mv api ta_api
cd ../modules && luadoc -d lua --doclet lua/tadoc $| --ta-home=$(ta_home)
--
cgit v1.2.3