Better docs (#241)

* website skeleton * updated bunder to 2.0, added caching * fix missing plugins? * enable deploy for the branch, try to save cache * need to use relative path? * fix missing css * use doc theme * really enable doc theme? * mayeb this time * come on baby * how about now * please ? * pretty please * ehhh * working theme * added hooks * formatting * formatting 2 * added doc yaml from bgforge mls 1.0.7 * no need for nav order * link reference * hooks on top * added global scripts * pages are generated, exclude them * generate site * pip3 ? * maybe now * hooks page is generated automatically * added table of contents to pages * don't waste so much space * switch highlight classes * mark functions as code in description * more formatting * reformat doc with python * loaded offsets * opcode is loaded into yaml, txt no longer necessary * mark unsafe functions * restore hooks page * clarification * deduplicated hooks doc * saner TOC * typo * move more docs * hook scripts doc is now in md * arrays doc is now in md * added data types page * added more info about old behaviour * minor formatting issues * moved more function docs to yaml * all sfall functions docs are transpiled to yaml format * formatting * fix format * add subcategory support * simplified yaml format, added structure doc * simplified structure and added clarification * generated a separate page for hook types * formatting * disambiguation * format clarification * move get_map* to subcategory: doc is not relevant for other functions * simple permalink * fix links * included more info on the main page * more clarification * rename offset > opcode * try to get more sensible baseurl * added best practices page * what's up with the slashes * allow parent pages with no content * separate docs for direct memory access functions * added latest functions * fixed hook types link * move get_explosion_damage to macros * removed duplicated comment * removed old comments * added hook ids * lowercase sfall * more sfall lowercasing * added proper permalinks * changes from mr.stalin * fix typos * clarification * fix direct memory access page * fixed top navlink * fixed urls * checked sfallgv.sav, it's really not bloating much * format clarification * shorter name * add mixed data type, sort * add proc type, link hooks functions * use same terminology * added bool * rearranged index * added unsafe label * move to root * add stats * more upper/lowercase * should work now * added build status * added combat category, added description for modified_ini, moved global script functions into a subcat * special note for set_self * typo * enable children * cleanup * move lists to arrays * show header filename for macro instead * rearrange more items to be more intuitive * build on bionic * separate object manipulation * added object manipulation link to home * typo * formatting * Added a note about charges * punctuation * formatting * moved floor2 to math * changed label color * moved art and appearance to animations * name too long * search note * moved exex_map_update to maps category * moved more functions from other to skills * too much blue * formatting * moved art_cache_clear to art section * empathize that var name must be exactly 8 characters long * update usages for inc_npc_level * separate objects, scripts and variables * updated url * moved get_string_pointer to strings * updated add_extra_msg_file doc * typo * latest doc updates from develop * updated default layout from upstream * applied local changes: subcategory list * remove unnecessary backticks * added new functions * fix STD_PROCEDURE_END display * formatting * don't fail on missing hook id * formatting * updated doc from upstream * added optimization and sslc pages * order ssl and optimization pages below home * really order optimization on top * merge objects_in_radius variants * updated from upstream * tone down link color * fixed formatting for updated theme * updated travis for ruamel * added favicon * restored separator between functions * updated functions.yml * updated sfall functions * rearranged some window and object function * hook updates, pre-arg renaming * hook args renumbering * merged upstream * added new hooks and functions from upstream * remove the long-winded note about macro * switch to gha for jekyll deployment * sudo for deps * try to fix ruamel missing * switch build to master only, ref https://github.com/phobos2077/sfall/pull/241#discussion_r580365212 * update status badge for https://github.com/phobos2077/sfall/pull/241
2026-07-27 16:52:34 -07:00 · 2021-02-24 11:40:24 +03:00
parent 5b3a83df91
commit 5f0c5ae1fa
37 changed files with 4091 additions and 0 deletions
@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+# coding: utf-8
+
+import sys, os
+import ruamel.yaml
+yaml = ruamel.yaml.YAML(typ="rt")
+yaml.width = 4096
+yaml.indent(mapping=2, sequence=4, offset=2)
+
+functions_yaml = sys.argv[1]
+hooks_yaml = sys.argv[2]
+md_dir = sys.argv[3]
+
+# template for functions pages
+function_header_template = '''---
+layout: page
+title: '{name}' # quote just in case
+nav_order: 6
+{has_children}
+# parent - could be empty
+{parent}
+has_toc: false
+permalink: {permalink}
+---
+
+# {name}
+{{: .no_toc}}
+'''
+
+# template for hooks types page - hardcoded
+hooks_header = '''---
+layout: page
+title: Hook types
+nav_order: 6
+parent: Hooks
+permalink: /hook-types/
+---
+
+# Hook types
+{: .no_toc}
+
+* TOC
+{:toc}
+---
+'''
+
+def get_slug(string):
+  return string.lower().replace(' ','-').replace(':','-').replace('/','-').replace('--','-')
+
+# functions pages
+with open(functions_yaml) as yf:
+  data = yaml.load(yf)
+  for cat in data: # list categories
+    text = ""
+
+    # check for childre
+    has_children = ""
+    children = [x for x in data if "parent" in x and x["parent"] == cat["name"]]
+    if len(children) > 0:
+      has_children = "has_children: true"
+
+    # used in filename and permalink
+    slug = get_slug(cat['name'])
+
+    # if parent is present, this is a subcategory
+    parent = ""
+    if 'parent' in cat:
+      parent = "parent: " + cat['parent']
+    header = function_header_template.format(name=cat['name'], parent=parent, has_children=has_children, permalink="/{}/".format(slug))
+    text += header
+
+    # common doc for category
+    if 'doc' in cat:
+      text = text + '\n' + cat['doc'] + '\n'
+
+    if len(children) > 0:
+      text += "\n## Subcategories\n{: .no_toc}\n\n"
+      for c in children:
+        text += "- [**{}**](/{}/)\n".format(c["name"], get_slug(c["name"]))
+      text += "\n"
+
+    if 'items' in cat: # allow parent pages with no immediate items
+      text += "## Functions\n{: .no_toc}\n\n"
+      text += "* TOC\n{: toc}\n"
+      # individual functions
+      items = cat['items']
+      items = sorted(items, key=lambda k: k['name'])
+
+      for i in items:
+        # header
+        text += "\n---\n\n### **{}**\n".format(i['name'])
+        # macro label
+        if 'macro' in i:
+          text += "{: .d-inline-block }\n" + format(i['macro']) + "\n{: .label .label-green }\n"
+        # unsafe label
+        if 'unsafe' in i and i['unsafe'] is True:
+          text += '{: .d-inline-block }\nUNSAFE\n{: .label .label-red }\n'
+        # usage
+        text += "```c++\n{}\n```\n".format(i['detail'])
+        # doc, if present
+        if 'doc' in i:
+          text += i['doc'] + '\n'
+
+    md_path = os.path.join(md_dir, slug + ".md")
+    with open(md_path, 'w') as f:
+      f.write(text)
+
+
+# hook types page
+with open(hooks_yaml) as yf:
+  hooks = yaml.load(yf)
+  hooks = sorted(hooks, key=lambda k: k['name']) # alphabetical sort
+  text = hooks_header
+
+  for h in hooks:
+    name = h['name']
+    doc = h['doc']
+    try:
+      hid = h['id']
+    except:
+      hid = "HOOK_" + name.upper()
+    if 'filename' in h: # overriden filename?
+      filename = h['filename']
+    else:
+      filename = "hs_" + name.lower() + ".int"
+
+    text += "\n## {}\n\n".format(name) # header
+    if filename != "": # if not skip
+      text += "`{}` ({})\n\n".format(hid, filename) # `HOOK_SETLIGHTING` (hs_setlighting.int)
+    text += doc # actual documentation
+
+    md_path = os.path.join(md_dir, "hook-types.md")
+    with open(md_path, 'w') as f:
+      f.write(text)