Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

custom luadoc generation #2821

Merged
merged 1 commit into from
Aug 28, 2024
Merged

custom luadoc generation #2821

merged 1 commit into from
Aug 28, 2024

Conversation

skarph
Copy link
Contributor

@skarph skarph commented Aug 23, 2024

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.

(had a minor crisis using git rebase, had to reset the branch entirely and submit another pr)

@tomlau10
Copy link
Contributor

off topic

I noticed your force pushes just now, haha 😂
I tried to checkout your pr branch at that time and see that you merged upstream/master into your master, and this is the start of the problem.

Here is what I would do if I were in your situation 👀

Actually your original pr contains three commits:

  • custom doc builder
  • changelog for custom docgen
  • enforce '\n' newlines

What we want to achieve:

squash all 3 as one
(because each commit just changes the line endings of the whole file in previous commit)

How to do so

Here is one of the way

  • First create a temp branch at your 2nd commit (changelog for custom docgen)
  • then cherry-pick your 3rd commit (enforce '\n' newlines)
    such that now the temp branch has 3 commits without any merge from upstream/master
  • finally use rebase interactively at the parent commit of your 1st commit
  • pick 1st commit, and choose fixup/squash for the 2nd & 3rd commit => start rebase
  • 🎉 now this temp branch is clean, without any changing the whole file things
    you can then checkout master again and hard reset it to temp, then force push master

ps: btw I usually won't use master as a PR branch, but that's another thing 😄

@sumneko sumneko merged commit eb0bf98 into LuaLS:master Aug 28, 2024
11 checks passed
@sumneko
Copy link
Collaborator

sumneko commented Aug 28, 2024

Great work, thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants