Skip to content

Instantly share code, notes, and snippets.

@benrob0329
Last active Sep 13, 2022
Embed
What would you like to do?
Minetest-Docs Project Proposal

The Minetest-Docs Project Proposal

Current Team Members

  • appguru / LMD

  • benrob0329

  • erlehmann

  • exe_virus

  • GreenXenith

  • ROllerozxa / Sublayer plank

  • j45

  • josiah_wi

  • wsor

Goals

These goals are intended to be accomplished in no particular time frame, however they are listed here roughly by priority.

  1. Document the entire Lua API, it’s parameters, and return types consistently and in an easy to understand manner

  2. Provide snippets for the recommended way to use non-trivial API componenets in as simple a manner as is practical

  3. Cross reference engine source code (C++ and Lua) for ease of access

  4. Cross reference existing documentation where more applicable (such as the Modding Book for tutorials, and the MTE repo for engine internals)

  5. Host larger examples for more complex behavior and recommended API usage

  6. Document engine limitations and known issues where applicable

  7. Cover APIs other than the modding API, such as the menu API

Repository Requirements

We request the following from celeron55:

Repository Policies

  • All proposed changes must have 1 or more approvals from a Minetest-Docs team member other than the proposer, so as long as said approval is not also contested by another Minetest-Docs team member

Documentation Requirements

  1. To clearly show and explain the Minetest Lua API

  2. To show and explain Lua examples for said API

  3. To be linkable from The Web for ease of reference

  4. To be accessible to any reader, regardless of skill level

  5. To be accessible offline (not including hyperlinks to external resources)

  6. To be able to be parsed by tooling, bots, and IDE plugins

Through these requirements, the following necessary features have been deduced:

  • Basic text, source code (preferably with syntax highlighting), tables, section links

  • The ability to convert to HTML for static site hosting

  • Macros or other meta features to assist with custom styling and constructs

  • Notifiers (Info: and Warning:) as a nice-to-have

  • Data output, library availability, or good consistency for easy parsing by tools

Through a loose vote (and some bikeshedding) we have concluded that AsciiDoc is our format of choice.