jtackaberry / luadox Goto Github PK

I am trying to use Luadox and I am having an issue with the generated documents.

For example if I have the following definition:

--- @section API

--- Returns a JSON document with basic node configuration
--
-- @example
--   { "version": "meshchat_version",
--     "node": "node_name",
--     "zone": "meshchat_zone_name" }
function config()
    print("Content-type: application/json\r")
    print("\r")
    print(string.format([[{"version":"%s","node":"%s","zone":"%s"}]], app_version, node_name(), zone_name()))
end

The generated documentation in the summary looks like the following:

It seems no matter what I do I can not prevent the detailed documentation from being inserted into the summary. The details are fine in the full definition of the function, but not in the summary.

Is there something that I am doing wrong or something that I am not understanding from the documentation?

Hello Jason,

Thanks a lot for your huge work, I just finished my migration from LDoc tu Luadox and I'm very happy with it !

So, here is a feature request I'd like to suggest, in LDoc we got the ability to use @fixme and @todo tags directly into the code, which let devs the possibility to point / to pin issues and track them (but yes, it was quite tedious to get those symbols in a usable list).

Could it be possible to create this kind of behaviour as we could use such tags and have an auto-generated list of references (file name, lines, comments) it would really help to document issue.

regards

Hello,

Just to mention calling python on windows is "python luadox -c luadox.conf" and not "python3 luadox -c luadox.conf"

First, thanks for the great work. I have noticed that if you use a tab for the whitespace on either side of the =, it won't document the field.

--- The table that this class was inherited from.
--@type table
LuaClass.__Super = nil

So this fails.
LuaClass.__Super =<\t>nil

documentation on nested tables is not helpful "allows nesting where field names are fully qualified based on the encapsulating table(s)" what does "fully qualified" mean, its really not helpful.

hello！I have some questions.
When I run the code,
D:\UGPRoot\game\Content\Script>python luadox -c luadox.conf [INFO] parsing D:\UGPRoot\game\Content\Script\init.lua [INFO] preprocessing 0 pages [INFO] generating search index

I don't understand the structure of the init.lua.
Can you provide a example of the init,lua?
Thanks!

@class tag appends the file to the front of the name in the index. So where my classes each have their own file, it does this:

how do I fix this? it's very frustrating and very stupid.

Hi,

is there any way to get the parsed structures in a format that can be processed by other applications?

I'd like to use a JSON or Lua table representation of the API to generate content dynamically so that it can be embedded in a static documentation website (created by Docusaurus). While serviceable, the website that luadox generates by default doesn't lend itself well to customization, and I can think of other ways to process the API structures that would be useful to me as well.

I see they're stored in the Parser class, but I'm not sure if the internal layout is appropriate if dumped. Ideally, I would have something along the lines of Blizzard's WOW API documentation that could easily be used to populate React components in Docusaurus, but any standardized format would likely work.

Do you think this would be possible, and if yes what approach would you suggest?

There's currently no support for this, and it's kind of tedious

Hi,

First of all, I would like to say thanks for creating this tool. I'm working with a Lua framework on a daily basis and was positively surprised when checking the generated documentation files.

However, I noticed that for some string values, a Python UnicodeDecodeError is getting raised when the Lua source file is getting parsed.

From performing some debugging, it became clear that the error occurs because there is some Greek string value present in the last file before the file mentioned by the command output (so in this case, the Greek string value was present in Kids.tws, not in Navigation.tws).

The issue got fixed by removing the following line of code from the Kids.tws file: local test = "ΠΡΟΒΟΛΗ ΤΟΥ ΒΙΝΤΕΟ ΕΙΣΑΓΩΓΗΣ"

Will non-Unicode characters also be supported in the future? Or some way to indicate that a specific piece of code should be ignored by LuaDox, perhaps something like a @ignore tag?

Kind regards,

Dieter

I am not certain if luadox can do this or not, but I have been a few different things and noting seems to work. I would like to include additional Markdown files in the generated output to produce full documentation for an application. luadox works good to generate documentation from the code, but it would also be nice to include other Markdown file that might discuss installation, architecture, troubleshooting, etc. It would also be great if there was come control over the layout of the navigation sidebar so that files could be ordered. I recognize that this might be a bit out of scope for luadox, but figured I would ask if there was functionality.

The other way I could see this working (but again I am not certain if the functionality is actually there) is to use a static site generator to create the documentation then just insert the generated documentation from luadox. But what I have seen does not seem to lend itself to being imported into any framework. It might be doable if luadox could generate an HTML file for each module rather than create a single index.html that has all modules included.