search

jtackaberry / luadox

Lua API documentation generator
Apache License 2.0
15 stars 2 forks source link

Possible to include Markdown files? #7

Closed hickey closed 9 months ago

hickey commented 9 months ago

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.

jtackaberry commented 9 months ago

LuaDox calls these manual pages.

https://github.com/jtackaberry/luadox#manual-pages

Take a look here for an example:

https://github.com/jtackaberry/rtk/blob/master/doc/luadox.conf

jtackaberry commented 9 months ago

As for customizing the sidebar order / layout, you're right that this isn't currently possible.

Manual pages will be listed based on the order in the config file, but classes and modules are always sorted lexically.

I'm not sure how worthwhile it is to control the ordering, although I have been thinking some sort of folder structure or grouping would be useful for large projects.

hickey commented 9 months ago

Actually, what you have is pretty much what I was looking for. I should have looked at the documentation more closely. I have to commend you on the amount of documentation that you do have although sometimes it feels overwhelming and it is easier to just go off and experiment to find a solution.

For the moment ordering of the manual pages via the config file works for the size of my project. I can envision a larger project needing a bit more control and breaking the documentation up by folder structure probably makes the biggest sense to me. I would think that ordering of the contents of the folder would be very desirable and probably a local config file/special file in the folder would be the way I would prefer to see controlling the structure for the folder. Sort of a bit more like how some of the static site generators operate. Effectively allowing each folder to be managed and operate in a standalone manner.

I can also envision for a folder with a lot of content the ability to structure files in two (maybe three?) levels in the sidebar. Another crazy idea might be a setting for the folder that allows the topics to be collapsible (folder level) when not currently being viewed. This should be conditional as there may be a folder or two that should always show the structure in the sidebar.

I hope this is useful ideas/suggestions for your plans.