Guide to autowiki

Autowiki

Autowiki is a neat way of creating automatically generated wiki templates.

If you are tasked with updating a large amount of sprites or information about a feature or system, you may see it fit to add an Autowiki to do.

Why Autowiki?

Autowiki, while appearing complex to set up at first, will keep a page 100% up to date with the code-base for all future changes to that feature automatically.

This means you don't have to go in edit the page for the smallest of changes or to update sprites - the script, which runs daily, will do it for you.

Where to begin

To begin, you need to create the actual Autowiki datum that collates all the data you are adding.

You will need a decently firm understanding of the game's code to accomplish this.

The most important thing to note in the datum is the "include_template" proc. This proc is passed a template title and a list of data which is later passed to the wiki

Ok, I made the datum, how do I test it?

Easiest way to test your setup is to look for "#define AUTOWIKI" in the code and uncomment it. Then, compile and run.

In your local data files, you will see two relevant files - "Autowiki_edits.txt", which contains all the raw text for your setup, and "Autowiki_files", which is a folder of images created by your setup.

There, you can verify it all looks correct.

And how do I apply it to the wiki?

When all is said and done, the Autowiki datum doesn't create the templates themselves - it creates data and automatically shoves it into templates for you to use elsewhere.

You must make your own templates for the data to fill in.

Once you have your base templates created, an easy way to test it is to manually enter some of your generated data to see how it works.

Once you are happy, you can submit your code as a pull request. Once it's merged, all is done!

Example

We'll go under two examples, one sample and one real world.

Sample

Let's create a simple sample of an Autowiki.

We start with the datum. The important thing to set here is the "page" variable. This will be the location of the finished product / template on the wiki. This is what people (you) will use to put your result onto your page.

 /datum/autowiki/my_sample
   page = "Template:Autowiki/Content/MyNewAutowikiSample"

The only proc you MUST implement is called generate. It, well, generates the template. It's where all the code goes.

 /datum/autowiki/my_sample/generate()

Two important procs of the datum to know are upload_icon and include_template. Another handy proc is escape_value.

Let's talk about the upload_icon first. If you want to upload images as a part of your code, you can do so with this proc. We will upload an image of a lizard plushie as an example.

 /datum/autowiki/my_sample/generate()
   // Creates a lizard plushie to take a snapshot of
   var/obj/item/plushie/lizard/edits_the_wiki = new()
   // Decides the filename of the resulting PNG. 
   var/filename = "test_lizard"
   // Uploads an image of the lizard to the wiki, with the file "Autowiki-test_lizard.png". 
   // Note, attempting to split your images into subfolders will NOT work. 
   upload_icon(getFlatIcon(edits_the_wiki, filename)

Next, let's look at include_template This is the bread and butter of creating templates. We will create a table with our lizard image we just created.

 /datum/autowiki/my_sample/generate()
   var/obj/item/plushie/lizard/edits_the_wiki = new()
   var/filename = "test_lizard"
   upload_icon(getFlatIcon(edits_the_wiki, filename)
   ...
   // This is a sample of what template data might look like. 
   // In actual practice this will be filled almost entirely automatically. 
   var/list/template_data = list(
       "icon" = filename,
       "table_text" = "THAT is a lizard.", 
   )
   // This is essentially taking the template you pass and creating a fully filled out result with your data. 
   // Instead of having to manually write { {Autowiki/MyNewAutowikiSampleTemplate|icon="test_lizard"|table_text="THAT is a lizard."} }, 
   // It's just filling it on for you! 
   // While it seems a little silly in this small sample, when you're handling hundreds of things, this saves a ton of time. 
   return include_template("Autowiki/MyNewAutowikiSampleTemplate", template_data)

The last relevant proc is escape_value. Its use is simple, it formats text in a way that won't break wikicode. Pretty much all text you're sending to the wiki should be wrapped in this proc.

That's it for the datum side.

All you need to do now is create the template Autowiki/MyNewAutowikiSampleTemplate how you see fit.

Real Example

See: https://github.com/tgstation/tgstation/pull/74931 .

This datum goes through all soup reagent datums and extract a lot of information related to them - name, ingredients, food types, and so on. It formats them all nicely in a list, then passes the list to a template, https://tgstation13.org/wiki/Template:Autowiki/SoupRecipeTemplate .

Each soup entry uses one of the above templates.

Finally, when all soups are parsed through, it wraps the entire output in this template https://tgstation13.org/wiki/Template:Autowiki/SoupRecipeTableTemplate to format it in one big text:

As a result, you get the following content template, automatically generated:

https://tgstation13.org/wiki/Template:Autowiki/Content/SoupRecipes