Custom doc builder

[skarph]

Exposes Lua.docScriptPath as a config value, which should be a path that points to a user's documentation script. This script overrides /script/cli/doc/export.lua , which is used by the server to export docs.

Here is the API, all of which can be overriden by the userscript:

• export.getLocalPath(uri): Called when the documentation needs to get the path of a source relative to the DOC path. Returns the relative path, or the absolute path, prefixed with the string '[FOREIGN]'

• export.positionOf(rowcol): Wrapper for guide.positionOf(rowcol[1], rowcol[2])

• export.sortDoc(a,b): A comparison function used by table.sort that is used to sort every piece of documentation in alphabetical order.

• export.documentObject(source, has_seen): A function that gets called on every source object. It is responsible for filtering each source to their corresponding export.makeDocObject[<TYPE>] function

• export.makeDocObject[<TYPE>]: A table of functions that are responsible for building their corresponding <TYPE>'s documentation. TYPES include 'type', 'variable', 'doc.class', etc. 'INIT' corresponds to every documentation object before it is processed by its corresponding type.

• export.gatherGlobals(): Called when the documentation needs an exhaustive list of the globals it should export documentation. By default this includes the result of vm.getAllGlobals(). Returns the collected variables/types.

• export.makeDocs(globals, callback): Documents globals from export.gatherGlobals() by calling export.documentObject on each one; updates its progress by calling callback when a global is finished being documented. Returns a table of the collected documentation

• export.serializeAndExport(docs, outputDir): Serializes documentation tables from export.makeDocs to json and markdown, Writes them to <outputDir>/doc.json and <outputDir>/doc.md, respectively. Returns these paths.

By default Lua.docScriptPath is "" and will execute the default documentation generation script at script/cli/doc/export.lua (with the above specified default behaviors).

For convenience, the script/vm/compiler.lua module now has a function vm.getSimpleClassFields, which can be used to get class fields without them recursing into other classes.

This has only been tested running the server manually with the --doc and --doc_out_path parameters, it has not been tested it by running it in VSC.

I made this because documentation was getting very unwieldy to generate, and saw doc sizes shrink by a factor of 10 when a custom documentation script was applied.

[tomlau10]

Hi @skarph , I see that you have pushed new commits to solve the line ending issues of script/vm/compiler.lua, 👍 but you did that in 2 different commits, that will just leave double of the diffs in the git history when this pr get merge. 😅

• In your 1st commit, you changed the whole file script/vm/compiler.lua
• And in your 2nd commit, you changed the whole file again
• doubled the damage... 🙈 as it will leave records in git history twice

You should probably do that by squash / amend force push to completely eliminate them in the git history. 😄
Or even simpler: mix reset everything and commit them 1 by 1 from the start then force push