reStructured text formatting

The LIMA mudlib supports reStructured text (RST) for documentation. Modules, commands and functions are documentation by using in file comments.

Module documentation:

//: MODULE

// This is the description of this module.

// $$see: another_module

Documentation for functions:

//: FUNCTION funcname

//This is the doc for function funcname

Documentation for commands:

//: COMMAND

//This is the doc for the (wiz) command

Docummentation for player commands:

//: PLAYER_COMMAND

// This is the doc for the player command

// $$see: other_cmd

Documentation for hooks:

//: HOOK

// This documents a hook called with call_hooks

Example code:

//: EXAMPLE

// This is an example to illustrate some code.

To do items that needs handling:

//: TODO

// What we'd like to do with this in the future

Another way of adding things we need to fix later:

// ### Something has to be fixed

// ### This doesn't need to start at the left margin

reStructured text tips

Most things about RST is handled by the RST_D when generating the documentation stored under /help/autodoc/, but a few things are worth noting:

Indented text needs a pipe to not get wrapped into a single line:

//: PLAYERCOMMAND
// USAGE
//
//   |  ``help``
//   |  ``help <topic>``
//

References to other help pages will be handled if written correctly in the comments. The “$$ see:” directive will be converted into links to other commands:

//: PLAYERCOMMAND
//$$ see: idea, typo, bug, question
// USAGE
//    ``feedback``

Use double reverse apostrophes (``) for marking commands and tips for wizards, e.g. score -t neon.

File names should be surrounded by asterisks to make them stand out in italic.

Testing your work

You will not be fluent in RST immediately, so testing your documentation initially will speed up the process of getting the layout that you want.

• Update the files on the MUD

• Run @RST_D->scan_mudlib() and wait for it to finish. It will automatically kick off HELP_D when it’s done to update statistics used by the docs command.

• Pick the written file from /help/autodoc/ and copy it to an online RST viewer and check if the layout is as you want it to be, e.g. https://rsted.info.ucl.ac.be/ but others work as well.

• Once happy with the RST, add an RST tag as per below.

An RST tag should be added to the end of the file as:

//
// .. TAGS: RST

It must be have empty line above to be recognized as a comment in RST. The RST_D and HELP_D will pick up these tags so they can be observed using the docs command. Other tags can be added as well and will be collected and summarized by the HELP_D.

HELP_D->query_tags()

for a mapping of tags and their according files.