Add Support for Generating HTML Documentation with LDoc

[AntumDeluge]

Adds HTML documentation generation using LDoc.

Live preview available here.

File explanation:

• gendoc.sh: Script for automating ldoc invocation (not needed for using workflow).
• .ldoc/config.ld: Configuration read by LDoc.
• .ldoc/parse_src.py: Script for generating temporary files to create topics for each item type.
  • An alternative to this is to separate equipment types into individual scripts or use multiple @topic calls in armor.lua using the --multimodule command line switch (PR 355)
• .ldoc/parse_settings.py: Script for generating a temporary file from settingtypes.txt that is LDoc readable.
• .ldoc/parse_crafts.py: Script for generating temporary file for crafting topic.

Usage:

Workflow:

A GitHub workflow is configured to generate documentation & deploy on the gh-pages branch when there is a push to master.

Manual:

To manually generate documentation, execute shell script gendoc.sh in the modpack root directory.

$ cd <3d_armor_dir>
$ ./gendoc.sh

By default, documentation files are exported to 3d_armor/docs/reference. This can be changed by setting export_dir environment variable:

$ export_dir="custom/path" ./gendoc.sh

Notes:

• The gendoc.sh script can be executed from any directory.
• The documentation generation currently depends on a custom LDoc branch. There are some upstream PRs that would make it compatible with the head branch:
  • 355
  • 359
• Because of limitations of current LDoc, I am using Python scripts to create some intermediate files for parsing & generating docs.
• HACKS:
  • LDoc is trimming "shields:" from shield item names (ex: "shields:shield_wood" is being changed to "shield_wood") for unknown reasons. config.ld is configured to re-add "shields:" prefix.

TODO:

• [x] add parameter data types:
  • [x] hitter from armor:punch (ObjectRef?)
  • [x] player & index from armor:run_callbacks (ObjectRef, int?)
  • [x] armor_element from armor:unequip (string?)
  • [x] preview from armor:add_preview
  • [x] item_name from armor:get_element (string?)
• [x] add parameter descriptions:
  • [x] base from armor:register_armor_group
  • [x] index & stack from armor:damage
  • [x] preview from armor:add_preview
  • [x] name & listring from armor:get_armor_formspec
  • [x] list from armor:serialize_inventory_list
  • [x] list_string from armor:deserialize_inventory_list
  • [x] msg from armor:get_valid_player
• [x] add details to ArmorDef
• [x] document registered armors in 3d_armor/armor.lua
• [x] document registered shields in shields/init.lua
• [x] document craft recipes
• [x] document remaining settings
• [x] put equipment types under their own topic, or put shields under "armor" (dependent on PR 355 or generating temp file for LDoc to read)
• [x] put craft recipes under separate topic (dependent on PR 355 or generating temp file for LDoc to read)
• [x] fix build checks
  • [x] luacheck
  • [x] integration-test (either move "docs" directory or figure out how to exclude it from the Minetest execution)
• [x] delete temporary 3d_armor/docs/settings.luadoc after HTML docs generated
• [x] remove unused parts of config.ld
• [x] use a more general custom_see_handler function (I'm not good with regular expressions)
• [x] use workflow to build docs on gh-pages branch
• [x] fix inventory image links
• [x] squash commits

Closes: #54

[AntumDeluge]

@SmallJoker, @BuckarooBanzay, if you have suggestions, I would like to hear them.

[BuckarooBanzay]

Wow, the docs look awesome :+1: i like the included items and settings

Just two questions:

• does it need your ldoc fork? (i see the LDoc 1.4.6-antum-dev in the footer)
• can we exclude the generated html-docs from the master branch and instead use a workflow to include them in the gh-pages branch? (not sure if you just did this here to show progress)

[AntumDeluge]

does it need your `ldoc` fork?

At the moment, yes. But I have put in a PR upstream to allow using Lua built-in objects & functions. If it doesn't get accepted, I would try to find some kind of workaround so main branch can be used, hopefully.

can we exclude the generated html-docs from the `master` branch and instead use a workflow to include them in the
`gh-pages` branch?

I am new to GitHub workflows, so you probably know better than I do. But I imagine it is possible. Will a workflow allow the docs to be generated on the gh-pages branch?

Edit: I just found an LDoc PR for this same thing. So I can most likely use it to learn how to build the docs on the gh-pages branch. That will help solve at least one of the issues I was having, I think, that was requiring using a custom LDoc.

[BuckarooBanzay]

I am new to GitHub workflows, so you probably know better than I do. But I imagine it is possible. Will a workflow allow the docs to be generated on the gh-pages branch?

no pressure, i've done that on some other repos and can do it here afterwards :+1:

[AntumDeluge]

@SmallJoker or @BuckarooBanzay: A couple questions:

1. Is armor_element parameter of armor:unequip a string? (code) figured this one out, it is a string value of "head", "torso", etc.
2. What is a good description for base parameter of armor:register_armor_group? (code) (Edit: I made it "Base armor value")

[AntumDeluge]

This is ready for review. But it does require my fork of LDoc to build the documentation (which is the version used in the workflow). And I think it will take some tweaking to get it to build with a GitHub workflow. The gendoc.sh script depends on ldoc command being in the PATH.

Currently, docs are created in the 3d_armor/docs/reference directory.

[AntumDeluge]

Oooh, I figured out how deploy on gh-pages branch using workflow. 🙂

As it is now, the documentation link will be: https://minetest-mods.github.io/3d_armor/reference

[AntumDeluge]

Forgot to change image links when I changed to building in gh-pages branch.

Edit: Not sure why images are not displaying for me in live preview. Hoping its a browser caching issue as it works for local builds. Turns out to be an issue with the Lua string global not being recognized on the remote build.

Edit: I just realized what the problem is. I put the import function in behind the UNSAFE_NO_SANDBOX flag. So I need to add that to the workflow command.

Edit: Fixed.

[AntumDeluge]

The only thing I would like better would be if the navigation panel wasn't static & didn't scroll with the rest of the page. I think maybe it can be done in CSS, but I'm not sure how.

Edit: Ooh, I just figured that out too. 🙂

[BuckarooBanzay]

A bit hard to test locally with all those github-links but it looks good :+1: Also: leafo/gh-actions-luarocks@v4 is new to me, i think this will help me somewhere else where i did that manually in a workflow

[AntumDeluge]

A bit hard to test locally with all those github-links

You mean the links to images? Perhaps it would be better to copy the images to the gh-pages branch so they can be linked locally?

[BuckarooBanzay]

Perhaps it would be better to copy the images to the gh-pages branch

Nah, thats ok how it is currently, copying it would result in redundant files (although git would handle that properly :thinking:)

[AntumDeluge]

@BuckarooBanzay #60 actually does change it to copy images to gh-pages branch.

[BuckarooBanzay]

Yeah i saw :laughing: I checked the repos i used my mtinfo mod on (it creates a static page with recipe infos) and i'm copying the textures there too to the gh-pages branch and it looks like git handles that pretty well :+1: (https://github.com/mt-mods/technic / https://mt-mods.github.io/technic/#/mods/technic/items)