DocLib [doclib]

A library to generate ingame manuals based on markdown files.

Browse on: GitHub

Download: GitHub

Introduction

DocLib is used to generate a manual as ingame documentation. The manual content is generated based on markdown files.

An advantage of this solution is the dual use of the documentation:

• A markdown file as web solution e. g. on GitHub
• A book as ingame manual

To generate a manual for your mod:

• Create your documentation as markdown file
• Copy the python script markdown_to_lua.py to your mod folder
• Add your markdown file to the python script (the last few lines)
• Install mistune with pip install mistune==0.8.4
• Run the script with python markdown_to_lua.py
• Implement the book node according to node.lua

Supported Markdown Markups

• Heading
• List
• Code block

In addition DocLib supports image links for the ingame manual:

• for node images: [doclib:manual|image]
• for PNG images: [doclib_book_inv.png|image]

See examples in manual_EN.md.

Construction Plans

This is a feature, mainly used by the mod techage to show construction plans of multi-block machines. But it can be used for any other mod, too.

A construction plan is a map with up to 12 * 10 fields. Each field can contain a node/item, text, or an image.

The arrangement is defined via a Lua table.

• Unused field elements are set to false
• For a text field (red mark) a table like {"text", "Pointless Demo"} is used
• For an item field (yellow mark) a table like {"item", "doclib_demo_img2.png", "Tooltip 1"} is used. The third value is a tooltip. It can be a string, a node name, or nil for no tooltip.
• For an image field (blue mark) a table like {"img", "doclib_book_inv.png", "2,2"} is used. The third value is the image size in fields (width x height).

This is an example of a map with 12 * 10 fields from the demo code in node.lua:

local ITEM1 = {"item", "doclib_demo_img1.png"}
local ITEM2 = {"item", "doclib_demo_img2.png", "Tooltip 1"}
local ITEM3 = {"item", "doclib_demo_img3.png", "Tooltip 2"}
local ITEM4 = {"item", "doclib_demo_img4.png", "Tooltip 3"}
local ITEM5 = {"item", "doclib_book_inv.png",  "doclib:manual"}
local ITEM6 = {"item", "doclib:manual",  "doclib:manual"}
local IMG_1 = {"img", "doclib_book_inv.png", "2,2"}
local TEXT1 = {"text", "Top view"}
local TEXT2 = {"text", "Pointless Demo"}
local TEXT3 = {"text", "End"}

local plan1 = {
	{TEXT2, false, false, false, false, false, false, false, false, false, false, ITEM4},
	{false, false, false, TEXT1, false, false, false, false, IMG_1, false, false, false},
	{false, false, false, false, false, false, false, false, false, false, false, false},
	{false, false, false, false, ITEM1, false, false, false, false, false, false, false},
	{false, false, false, ITEM4, ITEM5, ITEM2, false, false, false, false, false, false},
	{false, false, false, false, ITEM3, false, false, false, false, false, false, false},
	{false, false, false, false, ITEM6, false, false, false, false, false, false, false},
	{false, false, false, false, false, false, false, false, false, false, false, false},
	{false, false, false, false, false, false, false, false, false, false, false, false},
	{TEXT3, false, false, false, false, false, false, false, false, false, false, ITEM4},
}

doclib.add_manual_plan("doclib", "EN", "demo1", plan1)

With doclib.add_manual_plan the plan is stored under the name "demo1".

License

Copyright (C) 2023 Joachim Stolberg

Code: Licensed under the GNU AGPL version 3. See LICENSE.txt
Textures: CC BY-SA 3.0

Dependencies

none

History

• 2023-07-30 V1.00 * First commit