Some Fixes for HTML Docs Generated by LDoc (#60)

* LDoc: set min-height for "content" element
* LDoc: move generation script to .ldoc directory
* LDoc: add some output messages to gendoc.sh script
* LDoc: copy inventory image textures to reference dir instead of linking to remote files.
* LDoc: hack to compensate for "shields:" prefix being trimmed from item names
* Fix helmet_diamond & chestplate_crystal names in docstrings

.github/workflows/reference.yml

@@ -22,10 +22,8 @@ jobs:
       run: luarocks install --only-deps https://raw.githubusercontent.com/lunarmodules/LDoc/master/ldoc-scm-3.rockspec
     - name: Setup LDoc
       run: git clone --single-branch --branch=custom https://github.com/AntumDeluge/ldoc.git .ldoc/ldoc && chmod +x .ldoc/ldoc/ldoc.lua
-    - name: Generate temp files
-      run: chmod +x .ldoc/parse_*.py && ./.ldoc/parse_src.py && ./.ldoc/parse_settings.py && ./.ldoc/parse_crafts.py
     - name: Generate docs
-      run: ./.ldoc/ldoc/ldoc.lua --UNSAFE_NO_SANDBOX -c .ldoc/config.ld -d 3d_armor/docs/reference "$(pwd)"
+      run: chmod +x .ldoc/gendoc.sh && ./.ldoc/gendoc.sh
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       with:

.ldoc/config.ld

@@ -1,4 +1,5 @@
--- Place this file in mod "docs" directory
+
+-- place this file in mod ".ldoc" directory
 
 local print, type, string, table, tostring, tonumber, error, pairs, ipairs
 if import then
@@ -29,7 +30,8 @@ file = {
 	".ldoc/chestplates.luadoc",
 	".ldoc/leggings.luadoc",
 	".ldoc/boots.luadoc",
-	".ldoc/shields.luadoc",
+	--".ldoc/shields.luadoc",
+	"shields/init.lua",
 	".ldoc/crafting.luadoc",
 }
 
@@ -75,18 +77,9 @@ custom_tags = {
 	{
 		-- specify image basename only
 		"img",
-		title = "Image",
+		title = "Inventory Image",
 		format = function(value)
-			local img = "<img src=\"https://raw.githubusercontent.com/minetest-mods/3d_armor/master/"
+			return "<img src=\"../data/" .. value .. "\" style=\"width:32px; height:32px;\" />"
-			if string then
-				if string.find(value, "shields_") == 1 then
-					img = img .. "shields/"
-				else
-					img = img .. "3d_armor/"
-				end
-			end
-
-			return img .. "textures/" .. value .. "\" style=\"width:32px; height:32px;\" />"
 		end,
 	},
 	{
@@ -223,6 +216,11 @@ local registered = {
 }
 
 local function setting_handler(item)
+	-- avoid parsing again
+	if registered.settings[item.name] then
+		return item
+	end
+
 	if not ipairs or not type then
 		return item
 	end
@@ -275,15 +273,7 @@ end
 
 function custom_display_name_handler(item, default_handler)
 	if item.type == "setting" then
-		-- avoid parsing again
+		item = setting_handler(item)
-		if not registered.settings[item.name] then
-			item = setting_handler(item)
-		end
-	elseif item.type == "armor" and string then
-		-- HACK: not sure why "shields:" is being trimmed from item name
-		if string.find(item.name, "shield_") == 1 then
-			item.name = "shields:" .. item.name
-		end
 	end
 
 	if item then

.ldoc/gendoc.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+
+# Place this file in mod ".ldoc" directory.
+#
+# To change output directory set the `d_export` environment variable.
+# Example:
+#   $ d_export=/custom/path ./gendoc.sh
+
+
+d_ldoc="$(dirname $(readlink -f $0))"
+f_config="${d_ldoc}/config.ld"
+
+cd "${d_ldoc}/.."
+
+d_root="$(pwd)"
+d_export="${d_export:-${d_root}/3d_armor/docs/reference}"
+d_data="${d_export}/data"
+
+cmd_ldoc="${d_ldoc}/ldoc/ldoc.lua"
+if test -f "${cmd_ldoc}"; then
+	if test ! -x "${cmd_ldoc}"; then
+		chmod +x "${cmd_ldoc}"
+	fi
+else
+	cmd_ldoc="ldoc"
+fi
+
+
+# clean old files
+rm -rf "${d_export}"
+
+# generate items, settings, & crafts topics temp files
+echo -e "\ngenerating temp files ..."
+for script in "src" "settings" "crafts"; do
+	script="${d_ldoc}/parse_${script}.py"
+	if test ! -f "${script}"; then
+		echo "ERROR: script doesn't exist: ${script}"
+	else
+		# check script's executable bit
+		if test ! -x "${script}"; then
+			chmod +x "${script}"
+		fi
+		# execute script
+		"${script}"
+	fi
+done
+
+echo
+
+# generate new doc files
+"${cmd_ldoc}" --UNSAFE_NO_SANDBOX -c "${f_config}" -d "${d_export}" "${d_root}"; retval=$?
+
+# check exit status
+if test ${retval} -ne 0; then
+	echo -e "\nan error occurred (ldoc return code: ${retval})"
+	exit ${retval}
+fi
+
+echo -e "\ncleaning temp files ..."
+rm -vf "${d_ldoc}/"*.luadoc
+
+# HACK: ldoc does not seem to like the "shields:" prefix
+echo -e "\ncompensating for LDoc's issue with \"shields:\" prefix ..."
+sed -i \
+	-e 's/<strong>shield_/<strong>shields:shield_/' \
+	-e 's/<td class="name\(.*\)>shield_/<td class="name\1>shields:shield_/' \
+	-e 's/<a href="#shield_/<a href="#shields:shield_/' \
+	-e 's/<a name.*"shield_/<a name="shields:shield_/' \
+	"${d_export}/topics/shields.html"
+
+# copy textures to data directory
+printf "\ncopying textures ..."
+mkdir -p "${d_data}"
+texture_count=0
+for d_mod in "3d_armor" "shields"; do
+	printf "\rcopying textures from ${d_mod} ...\n"
+	for png in $(find "${d_root}/${d_mod}/textures" -maxdepth 1 -type f -name "*.png"); do
+		if test -f "${d_data}/$(basename ${png})"; then
+			echo "WARNING: not overwriting existing file: ${png}"
+		else
+			cp "${png}" "${d_data}"
+			texture_count=$((texture_count + 1))
+			printf "\rcopied ${texture_count} textures"
+		fi
+	done
+done
+
+echo -e "\n\nDone!"

.ldoc/ldoc.css

@@ -193,6 +193,7 @@ table.index td { text-align: left; vertical-align: top; }
     border-left: 2px solid #cccccc;
     border-right: 2px solid #cccccc;
     background-color: #ffffff;
+    min-height: 425px;
 }
 
 #about {

.ldoc/parse_src.py

@@ -17,7 +17,7 @@ armor_types = {
 	"chestplate": {"topic": "Chestplates", "values": []},
 	"leggings": {"topic": "Leggings", "values": []},
 	"boots": {"topic": "Boots", "values": []},
-	"shield": {"topic": "Shields", "values": []},
+	#"shield": {"topic": "Shields", "values": []},
 }
 
 def parse_file(f):

3d_armor/armor.lua

@@ -518,7 +518,7 @@ end
 if armor.materials.diamond then
 	--- Diamond Helmet
 	--
-	--  @helmet 3d_armor:_diamond
+	--  @helmet 3d_armor:helmet_diamond
 	--  @img 3d_armor_inv_helmet_diamond.png
 	--  @grp armor_head 1
 	--  @grp armor_heal 12
@@ -807,7 +807,7 @@ if armor.materials.crystal then
 	})
 	--- Crystal Chestplate
 	--
-	--  @chestplate 3d_armor:_crystal
+	--  @chestplate 3d_armor:chestplate_crystal
 	--  @img 3d_armor_inv_chestplate_crystal.png
 	--  @grp armor_torso 1
 	--  @grp armor_heal 12

gendoc.sh

@@ -1,38 +0,0 @@
-#!/usr/bin/env bash
-
-# place this file in mod "docs" directory
-
-root="$(dirname $(readlink -f $0))"
-docs="${root}/3d_armor/docs"
-config="${root}/.ldoc/config.ld"
-export_dir="${export_dir:-${docs}/reference}"
-
-cd "${root}"
-
-# clean old files
-rm -rf "${export_dir}"
-
-# generate items & settings topics temp files
-./.ldoc/parse_src.py
-./.ldoc/parse_settings.py
-./.ldoc/parse_crafts.py
-
-echo
-
-# generate new doc files
-ldoc --UNSAFE_NO_SANDBOX --multimodule -c "${config}" -d "${export_dir}" "${root}"
-retval=$?
-if test ${retval} -ne 0; then
-	# doesn't support "UNSAFE_NO_SANDBOX" or "multimodule" flag
-	echo
-	ldoc -c "${config}" -d "${export_dir}" "."
-	retval=$?
-	if test ${retval} -ne 0; then
-		exit ${retval}
-	fi
-fi
-
-# cleanup
-rm -f ./.ldoc/*.luadoc
-
-echo -e "\nDone!"

shields/init.lua

@@ -1,5 +1,5 @@
 
---- Registered shields.
+--- 3D Armor Shields
 --
 --  @topic shields