Skip to content

custom luadoc generation #2821

New issue

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

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

Already on GitHub? # to your account

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!

AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 12, 2025
File names in doc.json were broken since LuaLS#2821.
See discussion LuaLS#2971.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 12, 2025
Section luals.config was implemented in LuaLS#2562, but got lost
after a major refactoring in LuaLS#2821. This commit reimplements it.
See discussion LuaLS#2963.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 12, 2025
File names in doc.json were broken since LuaLS#2821.
See discussion LuaLS#2971.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 12, 2025
File names in doc.json were broken since LuaLS#2821.
See discussion LuaLS#2971.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 12, 2025
Section luals.config was implemented in LuaLS#2562, but got lost
after a major refactoring in LuaLS#2821. This commit reimplements it.
See discussion LuaLS#2963.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 13, 2025
Back then the default path of doc.json was LOGPATH.
However the default path got lost after a refactoring in LuaLS#2821.
This commit reimplements the default path, but changes
the default to the current directory.
AndreasMatthias added a commit to AndreasMatthias/lua-language-server that referenced this pull request Feb 13, 2025
Back then the default path of doc.json was LOGPATH.
However the default path got lost after a refactoring in LuaLS#2821.
This commit reimplements the default path, but changes
the default to the current directory.
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants