From 1a3a291bde12ad438bd95ea5df3c7b647df550d9 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 14:32:40 +0100 Subject: APIDump: Fixed bad for-loop. How did I not see this before? --- MCServer/Plugins/APIDump/main_APIDump.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index e5c8b9c30..06dd451d7 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -232,11 +232,11 @@ end function DumpAPIHtml() LOG("Dumping all available functions and constants to API subfolder..."); - LOG("Moving static files.."); + LOG("Copying static files.."); cFile:CreateFolder("API/Static"); local localFolder = g_Plugin:GetLocalFolder(); - for k, v in cFile:GetFolderContents(localFolder .. "/Static") do - cFile:Copy(localFolder .. "/Static/" .. v, "API/Static/" .. v); + for idx, fnam in ipairs(cFile:GetFolderContents(localFolder .. "/Static")) do + cFile:Copy(localFolder .. "/Static/" .. fnam, "API/Static/" .. fnam); end LOG("Creating API tables..."); -- cgit v1.2.3 From daeb37b27b9732bd34e02566f708f961bb6003a5 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 15:01:49 +0100 Subject: APIDump: Extra pages renamed to articles and moved to front. --- MCServer/Plugins/APIDump/main_APIDump.lua | 63 +++++++++++++++++++------------ 1 file changed, 39 insertions(+), 24 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 06dd451d7..c36285099 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -229,6 +229,32 @@ end +local function WriteArticles(f) + f:write([[ +

Articles

 +

The following articles provide various extra information on plugin development

+
"); +end + + + + + function DumpAPIHtml() LOG("Dumping all available functions and constants to API subfolder..."); @@ -308,12 +334,17 @@ function DumpAPIHtml()

The API reference is divided into the following sections:

+ ]]); + + WriteArticles(f); + + f:write([[

Class index

The following classes are available in the MCServer Lua scripting language:

+ ]]); + + f:write([[

Hooks

A plugin can register to be called whenever an "interesting event" occurs. It does so by calling @@ -352,30 +386,11 @@ function DumpAPIHtml() WriteHtmlHook(hook); end end - f:write([[ - + f:write([[ +

-

Extra pages

 - -

The following pages provide various extra information

- - "); - + ]]); + -- Copy the static files to the output folder (overwrite any existing): cFile:Copy(g_Plugin:GetLocalFolder() .. "/main.css", "API/main.css"); cFile:Copy(g_Plugin:GetLocalFolder() .. "/prettify.js", "API/prettify.js"); -- cgit v1.2.3 From 0c071c593787c1faa86349497101db42ffc92490 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 15:08:27 +0100 Subject: APIDump: Split the huge DumpAPIHtml function into smaller ones. --- MCServer/Plugins/APIDump/main_APIDump.lua | 108 +++++++++++++++++------------- 1 file changed, 61 insertions(+), 47 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index c36285099..67d6d1036 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -255,6 +255,65 @@ end +local function WriteClasses(f, a_API) + f:write([[ +

Class index

 +

The following classes are available in the MCServer Lua scripting language: +

    + ]]); + for i, cls in ipairs(a_API) do + f:write("
  • ", cls.Name, "
    • \n"); + WriteHtmlClass(cls, a_API); + end + f:write([[ +

+
+ ]]); +end + + + + + +local function WriteHooks(f, a_Hooks, a_UndocumentedHooks) + f:write([[ +

Hooks

 +

+ A plugin can register to be called whenever an "interesting event" occurs. It does so by calling + cPluginManager's AddHook() function and implementing a callback + function to handle the event.

+

+ A plugin can decide whether it will let the event pass through to the rest of the plugins, or hide it + from them. This is determined by the return value from the hook callback function. If the function + returns false or no value, the event is propagated further. If the function returns true, the processing + is stopped, no other plugin receives the notification (and possibly MCServer disables the default + behavior for the event). See each hook's details to see the exact behavior.

+ + + + + + ]]); + for i, hook in ipairs(a_Hooks) do + if (hook.DefaultFnName == nil) then + -- The hook is not documented yet + f:write(" \n \n \n \n"); + table.insert(a_UndocumentedHooks, hook.Name); + else + f:write(" \n \n \n \n"); + WriteHtmlHook(hook); + end + end + f:write([[ +
Hook nameCalled when
" .. hook.Name .. "(No documentation yet)
" .. hook.Name .. "" .. LinkifyString(hook.CalledWhen, hook.Name) .. "
+
+ ]]); +end + + + + + function DumpAPIHtml() LOG("Dumping all available functions and constants to API subfolder..."); @@ -343,53 +402,8 @@ function DumpAPIHtml() ]]); WriteArticles(f); - - f:write([[ -

Class index

 -

The following classes are available in the MCServer Lua scripting language: -

    - ]]); - for i, cls in ipairs(API) do - f:write("
  • ", cls.Name, "
    • \n"); - WriteHtmlClass(cls, API); - end - f:write([[ -

-
- ]]); - - f:write([[ -

Hooks

 -

- A plugin can register to be called whenever an "interesting event" occurs. It does so by calling - cPluginManager's AddHook() function and implementing a callback - function to handle the event.

-

- A plugin can decide whether it will let the event pass through to the rest of the plugins, or hide it - from them. This is determined by the return value from the hook callback function. If the function - returns false or no value, the event is propagated further. If the function returns true, the processing - is stopped, no other plugin receives the notification (and possibly MCServer disables the default - behavior for the event). See each hook's details to see the exact behavior.

- - - - - - ]]); - for i, hook in ipairs(Hooks) do - if (hook.DefaultFnName == nil) then - -- The hook is not documented yet - f:write(" \n \n \n \n"); - table.insert(UndocumentedHooks, hook.Name); - else - f:write(" \n \n \n \n"); - WriteHtmlHook(hook); - end - end - f:write([[ -
Hook nameCalled when
" .. hook.Name .. "(No documentation yet)
" .. hook.Name .. "" .. LinkifyString(hook.CalledWhen, hook.Name) .. "
-
- ]]); + WriteClasses(f, API); + WriteHooks(f, Hooks, UndocumentedHooks); -- Copy the static files to the output folder (overwrite any existing): cFile:Copy(g_Plugin:GetLocalFolder() .. "/main.css", "API/main.css"); -- cgit v1.2.3 From b99255820b00547ef49045117d7346a30999870c Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 15:26:41 +0100 Subject: APIDump: Added a quick-nav menu to class descriptions. First part of #403. --- MCServer/Plugins/APIDump/main_APIDump.lua | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 67d6d1036..42cd5bad4 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -255,7 +255,7 @@ end -local function WriteClasses(f, a_API) +local function WriteClasses(f, a_API, a_ClassMenu) f:write([[

Class index

The following classes are available in the MCServer Lua scripting language: @@ -263,7 +263,7 @@ local function WriteClasses(f, a_API) ]]); for i, cls in ipairs(a_API) do f:write("

  • ", cls.Name, "
    • \n"); - WriteHtmlClass(cls, a_API); + WriteHtmlClass(cls, a_API, a_ClassMenu); end f:write([[

    @@ -378,7 +378,19 @@ function DumpAPIHtml() LOGINFO("Cannot output HTML API: " .. err); return; end + + -- Create a class menu that will be inserted into each class file for faster navigation (#403) + local ClassMenuTab = {}; + for idx, cls in ipairs(API) do + table.insert(ClassMenuTab, ""); + table.insert(ClassMenuTab, cls.Name); + table.insert(ClassMenuTab, "
    "); + end + local ClassMenu = table.concat(ClassMenuTab, ""); + -- Write the HTML file: f:write([[ @@ -402,7 +414,7 @@ function DumpAPIHtml() ]]); WriteArticles(f); - WriteClasses(f, API); + WriteClasses(f, API, ClassMenu); WriteHooks(f, Hooks, UndocumentedHooks); -- Copy the static files to the output folder (overwrite any existing): @@ -860,7 +872,7 @@ end -function WriteHtmlClass(a_ClassAPI, a_AllAPI) +function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu) local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w"); if (cf == nil) then return; @@ -975,7 +987,11 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI)

    ]], a_ClassAPI.Name, [[

    -

    Contents

    +
    Quick navigation: + ]]); + cf:write(a_ClassMenu); + cf:write([[ +

    Contents

      ]]); @@ -1073,7 +1089,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI) end end - cf:write([[]]); + cf:write([[
    ]]); cf:close(); end -- cgit v1.2.3 From 9a9888a8cc0be28af5217de38f1154db97fa649a Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 15:36:28 +0100 Subject: APIDump: Added a quick-nav menu to hook descriptions. Second part of #403. --- MCServer/Plugins/APIDump/main_APIDump.lua | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index 42cd5bad4..fef827f3e 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -275,7 +275,7 @@ end -local function WriteHooks(f, a_Hooks, a_UndocumentedHooks) +local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav) f:write([[

    Hooks

    @@ -301,7 +301,7 @@ local function WriteHooks(f, a_Hooks, a_UndocumentedHooks) table.insert(a_UndocumentedHooks, hook.Name); else f:write(" \n " .. hook.Name .. "\n " .. LinkifyString(hook.CalledWhen, hook.Name) .. "\n \n"); - WriteHtmlHook(hook); + WriteHtmlHook(hook, a_HookNav); end end f:write([[ @@ -379,7 +379,7 @@ function DumpAPIHtml() return; end - -- Create a class menu that will be inserted into each class file for faster navigation (#403) + -- Create a class navigation menu that will be inserted into each class file for faster navigation (#403) local ClassMenuTab = {}; for idx, cls in ipairs(API) do table.insert(ClassMenuTab, ""); + table.insert(HookNavTab, (hook.Name:gsub("^HOOK_", ""))); -- remove the "HOOK_" part of the name + table.insert(HookNavTab, "
    "); + end + local HookNav = table.concat(HookNavTab, ""); + -- Write the HTML file: f:write([[ @@ -415,7 +426,7 @@ function DumpAPIHtml() WriteArticles(f); WriteClasses(f, API, ClassMenu); - WriteHooks(f, Hooks, UndocumentedHooks); + WriteHooks(f, Hooks, UndocumentedHooks, HookNav); -- Copy the static files to the output folder (overwrite any existing): cFile:Copy(g_Plugin:GetLocalFolder() .. "/main.css", "API/main.css"); @@ -1097,7 +1108,7 @@ end -function WriteHtmlHook(a_Hook) +function WriteHtmlHook(a_Hook, a_HookNav) local fnam = "API/" .. a_Hook.DefaultFnName .. ".html"; local f, error = io.open(fnam, "w"); if (f == nil) then @@ -1120,7 +1131,11 @@ function WriteHtmlHook(a_Hook)

    ]], a_Hook.Name, [[

    -

    +
    Quick navigation: + ]]); + f:write(a_HookNav); + f:write([[ +

    ]]); f:write(LinkifyString(a_Hook.Desc, HookName)); f:write("

    \n

    Callback function

    \n

    The default name for the callback function is "); @@ -1150,7 +1165,7 @@ function WriteHtmlHook(a_Hook) f:write("

    ", (example.Desc or "missing Desc"), "

    \n"); f:write("
    ", (example.Code or "missing Code"), "\n
    \n\n"); end - f:write([[]]); + f:write([[
    ]]); f:close(); end -- cgit v1.2.3 From e4c6e853eaa231f0c95235b02612ad35edf73dce Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 27 Dec 2013 15:48:01 +0100 Subject: APIDump: Added quick links to index to each class and hook file. Third part of #403. --- MCServer/Plugins/APIDump/main_APIDump.lua | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index fef827f3e..ff837ec4e 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -998,7 +998,13 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI, a_ClassMenu)

    ]], a_ClassAPI.Name, [[

    -
    Quick navigation: +
    + Index:
    + Articles
    + Classes
    + Hooks
    +
    + Quick navigation:
    ]]); cf:write(a_ClassMenu); cf:write([[ @@ -1131,7 +1137,13 @@ function WriteHtmlHook(a_Hook, a_HookNav)

    ]], a_Hook.Name, [[

    -
    Quick navigation: +
    + Index:
    + Articles
    + Classes
    + Hooks
    +
    + Quick navigation:
    ]]); f:write(a_HookNav); f:write([[ -- cgit v1.2.3 From 61af77a5c5c99ec82decc24ff8fca899f959e48a Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Sun, 29 Dec 2013 13:24:38 +0100 Subject: APIDump: Static files overwrite their destination. --- MCServer/Plugins/APIDump/main_APIDump.lua | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) (limited to 'MCServer/Plugins/APIDump/main_APIDump.lua') diff --git a/MCServer/Plugins/APIDump/main_APIDump.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index ff837ec4e..b3a95eb22 100644 --- a/MCServer/Plugins/APIDump/main_APIDump.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -321,6 +321,7 @@ function DumpAPIHtml() cFile:CreateFolder("API/Static"); local localFolder = g_Plugin:GetLocalFolder(); for idx, fnam in ipairs(cFile:GetFolderContents(localFolder .. "/Static")) do + cFile:Delete("API/Static/" .. fnam); cFile:Copy(localFolder .. "/Static/" .. fnam, "API/Static/" .. fnam); end @@ -428,11 +429,18 @@ function DumpAPIHtml() WriteClasses(f, API, ClassMenu); WriteHooks(f, Hooks, UndocumentedHooks, HookNav); - -- Copy the static files to the output folder (overwrite any existing): - cFile:Copy(g_Plugin:GetLocalFolder() .. "/main.css", "API/main.css"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/prettify.js", "API/prettify.js"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/prettify.css", "API/prettify.css"); - cFile:Copy(g_Plugin:GetLocalFolder() .. "/lang-lua.js", "API/lang-lua.js"); + -- Copy the static files to the output folder: + local StaticFiles = + { + "main.css", + "prettify.js", + "prettify.css", + "lang-lua.js", + }; + for idx, fnam in ipairs(StaticFiles) do + cFile:Delete("API/" .. fnam); + cFile:Copy(g_Plugin:GetLocalFolder() .. "/" .. fnam, "API/" .. fnam); + end -- List the documentation problems: LOG("Listing leftovers..."); -- cgit v1.2.3