Documentation generation does not respect `--configpath`

[rhys-vdw]

How are you using the lua-language-server?

Command Line

Which OS are you using?

Windows WSL

What is the issue affecting?

Other

Expected Behaviour

The specified config file should be used.

Actual Behaviour

The specified config is ignored, meaning that runtime.builtin cannot be customized for export. See #2977 (comment)

Reproduction steps

.luarc.docs.json

{
  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
  "runtime.version": "Lua 5.1",
  "runtime.builtin": {
    "basic": "disable",
    "bit": "disable",
    "bit32": "disable",
    "builtin": "disable",
    "coroutine": "disable",
    "debug": "disable",
    "ffi": "disable",
    "io": "disable",
    "jit": "disable",
    "math": "disable",
    "os": "disable",
    "package": "disable",
    "string": "disable",
    "table": "disable",
    "table.clear": "disable",
    "table.new": "disable",
    "utf8": "disable"
  }
}

lua-language-server --configpath .luarc.doc.json --doc ../.. --doc_out_path _data

See that builtins are included in doc output, despite being disabled in specified config file.

Additional Notes

Actually built-ins should not be included regardless: #2977

Log File

No response

[Mc-GrowlR]

Hello, have you solved this problem?
Here's a snippet of filtering code I used to filter the global variables and various libraries in the exported document:
Replace the document（script/cli/doc/export.lua） with this.
(The author of this code is not me

---builds a lua table of based on `globals` and their elements
---@async
---@param globals table
---@param callback fun(i, max)
function export.makeDocs(globals, callback)
    local docs = {}

    for i, global in ipairs(globals) do
        table.insert(docs, export.documentObject(global))
        callback(i, #globals)
    end

    table.sort(docs, export.sortDoc)

    --- 筛选
    local foreign = {}
    local filterout = { exitcode = 1, filetype = 1, gcoptions = 1, hookmask = 1, infowhat = 1, loadmode = 1, localecategory = 1, openmode = 1, popenmode = 1, readmode = 1, seekwhence = 1, type = 1, vbuf = 1 }
    for id, class in ipairs(docs) do
        if filterout[class.name] ~= nil then
            table.insert(foreign, id)
        elseif class.defines then
            for _, define in ipairs(class.defines) do
                if type(define.file) == "string" and not string.find(define.file, "test", 1, true) then
                    table.insert(foreign, id)
                    break
                end
            end
        end
    end
    for i, id in ipairs(foreign) do
        table.remove(docs, id - i + 1)
    end
    -- print("\n", "docs:\n", serialize(docs))

    return docs
end

You can try it and see how it goes.

[tomlau10]

基於覆寫 export.lua 方向的話，我想到更簡單的方法 🤔

• 直接改 export.gatherGlobals 並把屬於 built-in meta 文件路徑內所定義的 class 都直接篩走

local furi = require "file-uri"

function export.gatherGlobals()
    local metaPathUri = furi.encode(METAPATH)
    local all_globals = vm.getAllGlobals()
    local globals = {}
    for _, g in pairs(all_globals) do
        for uri in pairs(g.links) do
            -- ignore globals classes defined in built in metapath
            if uri:find(metaPathUri, 1, true) then
                goto continue
            end
        end
        table.insert(globals, g)
        ::continue::
    end
    return globals
end

---

Replace the document（script/cli/doc/export.lua） with this.

並且 #2821 其實提供1個 Lua.docScriptPath config 來覆寫 export.lua 的 function logic
不一定要直接改 server 自帶的 export.lua

• 所以可以將上邊內容 save 為1個 export.lua 放在 workspace root
• 然後 workspace 內的 .luarc.json 加上

    "docScriptPath": "export.lua",
    "workspace.ignoreDir": [
        "export.lua"
    ],

• 這樣當執行 lua-language-server --doc=. --doc_out_path=. 時，也能忽略所有 built in class

---

somehow the issue translate bot is not working ... 🙄
I manually translate #2997 (comment) using gpt4o:

Translated

If we're going to override export.lua, I have a simpler approach in mind 🤔

• Directly modify export.gatherGlobals and filter out all classes defined within the built-in meta file path.

local furi = require "file-uri"

function export.gatherGlobals()
    local metaPathUri = furi.encode(METAPATH)
    local all_globals = vm.getAllGlobals()
    local globals = {}
    for _, g in pairs(all_globals) do
        for uri in pairs(g.links) do
            -- ignore globals classes defined in built in metapath
            if uri:find(metaPathUri, 1, true) then
                goto continue
            end
        end
        table.insert(globals, g)
        ::continue::
    end
    return globals
end

---

Replace the file (script/cli/doc/export.lua) with this.

Also, #2821 actually provides a Lua.docScriptPath config to override the function logic in export.lua. You don't necessarily need to directly modify the server's built-in export.lua.

• So you can save the above content as export.lua in your workspace root.
• Then add the following to your workspace's .luarc.json:

    "docScriptPath": "export.lua",
    "workspace.ignoreDir": [
        "export.lua"
    ],

• This way, when you run lua-language-server --doc=. --doc_out_path=., all built-in classes will be ignored.

[Mc-GrowlR]

After my investigation, the reason why the configuration file does not take effect seems to be that it is not loaded

经过我的排查，配置文件没有生效的原因好像是它没有没加载。

[Mc-GrowlR]

In script/provider/provider.lua =》 m.register 'initialized' =》 m.updateConfig() ，The function is called。
It doesn't pass arguments when it's called, which is the cause of the error.
Maybe I should open another issue?

[Mc-GrowlR]

Hello, my PR seems to be able to help you solve this problem, after testing, the luarc configuration file you provided can be read normally, and the lua module can also be filtered in the exported document.