From 09e94bd947bec861424c7ebcb4351ab4f2d3cf7d Mon Sep 17 00:00:00 2001 From: William 'psyFi' Hatcher Date: Mon, 14 Aug 2017 22:32:28 -0500 Subject: Updated docs to mention InfoDump for creating README.md, etc. (#3895) --- CONTRIBUTORS | 1 + Server/Plugins/APIDump/InfoFile.html | 28 +++++++++++++++++++++++++++- Server/Plugins/APIDump/main_APIDump.lua | 2 +- Server/Plugins/InfoDump.lua | 8 ++++---- 4 files changed, 33 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 84af3215a..2b3c877d9 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -55,6 +55,7 @@ tonibm19 UltraCoderRU Warmist WebFreak001 +williamhatcher (Helped with API documentation updates and bug fixes) worktycho xoft (Mattes Dolak/madmaxoft on GH) Yeeeeezus (Donated AlchemistVillage prefabs) diff --git a/Server/Plugins/APIDump/InfoFile.html b/Server/Plugins/APIDump/InfoFile.html index e293931f2..4b35a41be 100644 --- a/Server/Plugins/APIDump/InfoFile.html +++ b/Server/Plugins/APIDump/InfoFile.html @@ -20,6 +20,7 @@
  • Commands table
  • ConsoleCommands table
  • Permissions table
    • +
  • Categories table
  • Using the file in code
  • Examples
    • @@ -34,7 +35,10 @@

    Last, but not least, we want to make a plugin repository on the web in the future, a repository that would store plugins, their descriptions, comments. It makes sense that the centralized information can be parsed by the repository automatically, so that advanced things, such as searching for a plugin based on a command, or determining whether two plugins collide command-wise, are possible.

    -

    After this file format has been devised, a tool has been written that allows for an easy generation of the documentation for the plugin in various formats. It outputs the documentation in a format that is perfect for pasting into the forum. It generates documentation in a Markup format to use in README.md on GitHub and similar sites. The clever thing is that you don't need to keep all those formats in sync manually - you edit the Info.lua file and this tool will re-generate the documentation for you.

    +

    A tool has been written that allows for an easy generation of the documentation for the plugin in various formats. It outputs the documentation in a format that is perfect for pasting into the forum. It generates documentation in a Markup format to use in README.md on GitHub and similar sites. The clever thing is that you don't need to keep all those formats in sync manually - you edit the Info.lua file and this tool will re-generate the documentation for you. +
    + To generate documentation for the plugin, activate the DumpInfo plugin on a cuberite server with your plugin installed, and use the webadmin interface to "Dump" the plugin information. This will create a README.md suitable for uploading to your git repo, and a forum_info.txt, which can be copy-pasted into a forum post. +

    So to sum up, the Info.lua file contains the plugins' commands, console commands, their permissions and possibly the overall plugin documentation, in a structured manner that can be parsed by a program, yet is human readable and editable.

    @@ -56,6 +60,7 @@ g_PluginInfo = Commands = {}, ConsoleCommands = {}, Permissions = {}, + Categories = {}, }

    As you can see, the structure is pretty straightforward. Note that the order of the elements inside the table is not important (Lua property).

    @@ -115,6 +120,7 @@ Commands = ["/cmd2"] = { Alias = {"/c2", "//c2" }, + Category = "Something", Subcommands = { sub1 = -- This declares a "/cmd2 sub1" command @@ -150,6 +156,8 @@ Commands =

    The permission element specifies that the command is only available with the specified permission. Note that the permission for subcommand's parent isn't checked when the subcommand is called. This means that specifying the permission for a command that has subcommands has no effect whatsoever, but is discouraged because we may add processing for that in the future.

    +

    The optional Categories table provides descriptions for command categories in the generated documentation. The documentation generator will group the commands by their specified Category ("General" by default) and each category will have the specified description written to it.

    +

    The ParameterCombinations table is used only for generating the documentation, it lists the various combinations of parameters that the command supports. It's worth specifying even if the command supports only one combination, because that combination will get documented this way.

    The Alias member specifies any possible aliases for the command. Each alias is registered separately and if there is a subcommand table, it is applied to all aliases, just as one would expect. You can specify either a single string as the value (if there's only one alias), or a table of strings for multiple aliases. Commands with no aliases do not need to specify this member at all.

    @@ -216,6 +224,24 @@ Permissions =

    The RecommendedGroup element lists, in plain English, the intended groups for which the permission should be enabled on a typical server. Plugin authors are advised to create reasonable defaults, prefering security to openness, so that admins using these settings blindly don't expose their servers to malicious users.

    +
    +

    Categories

     + +

    The optional Categories table provides descriptions for categories in the generated documentation. Commands can have categories with or without category descriptions in this table. The documentation generator will output a table of listed categories along with their description.

    +
    +Categories = 
+{
+	General =
+	{
+		Description = "A general, yet somehow vague description of the default category."
+	},
+	Something =
+	{
+		Description = "Some descriptive words which form sentences pertaining to this set of commands use and goals."
+	},
+},
+
    +

    Using the file in code

     diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index 0f1476ef7..fd243b25f 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -168,7 +168,7 @@ end --- Returns the timestamp in HTML format -- The timestamp will be inserted to all generated HTML files local function GetHtmlTimestamp() - return string.format("
    Generated on %s, Build ID %s, Commit %s
    ", + return string.format("
    Generated by APIDump on %s, Build ID %s, Commit %s
    ", os.date("%Y-%m-%d %H:%M:%S"), cRoot:GetBuildID(), cRoot:GetBuildCommitID() ) diff --git a/Server/Plugins/InfoDump.lua b/Server/Plugins/InfoDump.lua index 4dde35978..494ddd85f 100644 --- a/Server/Plugins/InfoDump.lua +++ b/Server/Plugins/InfoDump.lua @@ -306,7 +306,7 @@ local function WriteCommandsCategoryForum(a_Category, f) if (CategoryName == "") then CategoryName = "General" end - f:write("\n[size=Large]", ForumizeString(a_Category.DisplayName or CategoryName), "[/size]\n") + f:write("\n[size=large]", ForumizeString(a_Category.DisplayName or CategoryName), "[/size]\n") -- Write description: if (a_Category.Description ~= "") then @@ -377,7 +377,7 @@ local function DumpCommandsForum(a_PluginInfo, f) return end - f:write("\n[size=X-Large]Commands[/size]\n") + f:write("\n[size=x-large]Commands[/size]\n") -- Dump per-category commands: for idx, cat in ipairs(Categories) do @@ -425,7 +425,7 @@ local function DumpAdditionalInfoForum(a_PluginInfo, f) for idx, info in ipairs(a_PluginInfo.AdditionalInfo) do if ((info.Title ~= nil) and (info.Contents ~= nil)) then - f:write("\n[size=X-Large]", ForumizeString(info.Title), "[/size]\n") + f:write("\n[size=x-large]", ForumizeString(info.Title), "[/size]\n") f:write(ForumizeString(info.Contents), "\n") end end @@ -530,7 +530,7 @@ local function DumpPermissionsForum(a_PluginInfo, f) end -- Dump the permissions: - f:write("\n[size=X-Large]Permissions[/size]\n[list]\n") + f:write("\n[size=x-large]Permissions[/size]\n[list]\n") for idx, perm in ipairs(Permissions) do f:write(" - [color=red]", perm.Name, "[/color] - ") f:write(ForumizeString(perm.Info.Description or "")) -- cgit v1.2.3