Wiki grabber
From Wesnoth
Contents |
Introduction
The wiki grabber is a work in progress tool located at 'utils/wiki_grabber.py'. This tool can be used to extract specially formatted comment sections from a .cpp and convert it to wiki format. At the moment it mainly helps to get a table into wiki format.
The grabber is writting to make documenting the new GUI code easier so this is the only part of the source where this type of comment is used, this might change in the future.
Details
The tool will look for properly formatted comment section. Every section has a page name and order. When no order number a default is set. The tool will per page a list with sections, after all files are processed the data is stored, with a stable sort. After that for every page a text file with the wiki data is generated. Note if data for the same page is stored in different files it's highly recommended to add a sort value since there's no guarantee on the sorting order of files.
Comment format
The grabber will only extract information which is inside specially formatted comment blocks. The format is the following:
/*WIKI * header data * header data * * body data * body data * body data * line to be merged. */
- The space after the * is mandatory.
- The whiteline between header and body is also mandatory.
- If a line starts with at least 8 spaces it's joined with the previous line, mainly interesting for tables.
Header
The header has key value pairs the following keys are reconized
- @page the name of the page, mandatory
- @order the sorting order (optional default value 10000 (subject to change))
Body
The body text can have markup for the processor the rest of the text is put in the wiki as is. The only markup used at the moment is @start_table and @end_table. The text between these tags is transformed into a wiki table.
Tables
Tables start with
@start_table = foo
foo is the type of table, the following table formats are reconized:
- variable_types, Contains the variables types available to use, should be on the page GUIVariable.
- config, Contains the data which can/should be used in the WML for a certain item.
- formula, The variables available for certain formulas.
- window_definition, The defintion of a window and controls.
The table needs to end with
@end_table
In the description column of a table a @* can be used to create a list.
variable_type table
- variable separator description
- variable the name of the type being described
- is one or more spaces
- description is the description of the type
config table
- variable separator1 (type) separator2 description
- variable the name of the variable being described
- separator1 is a single space
- type [separator = separator default]
- type is the type of the variable (as defined in a variable_type table)
- separator is zero or more spaces
- separator is zero or more spaces
- default is a default value for the variable (if the optional default value is omitted, the default will get mandatory as text
- separator2 is one or more spaces
- description is the description of the variable
formula table
- variable separator1 type separator2 description
- variable the name of the variable being described
- separator1 is a single space
- type is th type of the variable (as defined in a variable_type table)
- separator2 is one or more spaces
- description is the description of the variable
window_definition
- variable separator description
- variable the name of the definition being described
- is one or more spaces
- description is the description of the definition