summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--CONTRIBUTORS1
-rw-r--r--Server/Plugins/APIDump/InfoFile.html28
-rw-r--r--Server/Plugins/APIDump/main_APIDump.lua2
-rw-r--r--Server/Plugins/InfoDump.lua8
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 @@
<li><a href="#Commands">Commands table</a></li>
<li><a href="#ConsoleCommands">ConsoleCommands table</a></li>
<li><a href="#Permissions">Permissions table</a></li>
+ <li><a href="#Categories">Categories table</a></li>
<li><a href="#Using">Using the file in code</a></li>
<li><a href="#Examples">Examples</a></li>
</ul>
@@ -34,7 +35,10 @@
<p>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.</p>
- <p>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.</p>
+ <p>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.
+ <br>
+ 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.
+ </p>
<p>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.</p>
@@ -56,6 +60,7 @@ g_PluginInfo =
Commands = {},
ConsoleCommands = {},
Permissions = {},
+ Categories = {},
}
</pre>
<p>As you can see, the structure is pretty straightforward. Note that the order of the elements inside the table is not important (Lua property).</p>
@@ -115,6 +120,7 @@ Commands =
["/cmd2"] =
{
Alias = {"/c2", "//c2" },
+ Category = "Something",
Subcommands =
{
sub1 = -- This declares a "/cmd2 sub1" command
@@ -150,6 +156,8 @@ Commands =
<p>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.</p>
+ <p>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.</p>
+
<p>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.</p>
<p>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.</p>
@@ -217,6 +225,24 @@ Permissions =
<hr />
+ <a name="Categories"><h2>Categories</h2></a>
+
+ <p>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.</p>
+<pre class="prettyprint lang-lua">
+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."
+ },
+},
+</pre>
+
+ <hr />
<a name="Using"><h2>Using the file in code</h2></a>
<p>Just writing the Info.lua file and saving it to the plugin folder is not enough for it to actually be used. Your plugin needs to include the following boilerplate code, preferably in its Initialize() function:</p>
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("<div id='timestamp'>Generated on %s, Build ID %s, Commit %s</div>",
+ return string.format("<div id='timestamp'>Generated by <a href='https://github.com/cuberite/cuberite/tree/master/Server/Plugins/APIDump'>APIDump</a> on %s, Build ID %s, Commit %s</div>",
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 ""))