[Docs] Improve docgen accessibility

[badosu]

I'm aggregating on this issue a few standing issues regarding the current generated documentation:

• Lack of type linking, e.g. a method returns UnitState it should link to the UnitState definition.
• Tables are not expanding to their fields, e.g. Platform or Engine
• Aliases are truncating, e.g. a|b|c... without offering a way to expand to their whole definition

This can be separated in other issues, but for now it's a reference we can work on.

[badosu]

If we don't find an external tool that fits what we want to have, maybe it makes sense for us to have a binary spitting markdown/html ourselves (maybe as part of lua-doc-extractor?), this way we can have our docs decoupled from whatever tool we're using to host the docs (Jekyll currently).

[rhys-vdw]

If we don't find an external tool that fits what we want to have, maybe it makes sense for us to have a binary spitting markdown/html ourselves (maybe as part of lua-doc-extractor?), this way we can have our docs decoupled from whatever tool we're using to host the docs (Jekyll currently).

lua-doc-extractor could be expanded to do full doc generation, but in theory we should be able to do generation from the lua library files in a way that is tool agnostic. A full, language aware parser and generator is not something we should have to maintain.

Moving to https://github.com/CppCXY/emmylua-analyzer-rust/tree/main/crates/emmylua_doc_cli should be the first test.

See discussion here: LuaLS/lua-language-server#3054

I'm not sure if it supports type linking, but I think we could upstream that feature, or potentially add it to a custom template for its generator.

[rhys-vdw]

#1983 has added emmylua_doc_cli as the generator.

Tables are not expanding to their fields, e.g. Platform or Engine

Fields are now shown, but field descriptions are lacking until rhys-vdw/lua-doc-extractor#9 is closed.

Lack of type linking, e.g. a method returns UnitState it should link to the UnitState definition.

It still lacks type linking (and it doesn't support @see attributes for manual type links).

Some upstream work will need to be done to get support for this as the doc generator does not add this information into the template at all.

However the doc generator is, in general, pretty nice and the code is very clean. The maintainer is open to PRs. Shouldn't be too hard to add this in ourselves.

Aliases are truncating, e.g. a|b|c... without offering a way to expand to their whole definition

I think this is better now. I can't find a specific example. Unfortunately there are instances where the aliased unions are not fully expanded (which would be fine if we had a type link or hover).

I think it would be useful to maintain a list of specific docs that have issues so we can start to tackle them one-by-one.