search

orbitersim / orbiter

Open-source repository of Orbiter Space Flight Simulator
MIT License
1.62k stars 220 forks source link

[Lua]Update API documentation #458

Closed TheGondos closed 6 months ago

TheGondos commented 7 months ago

This is a WIP for generating the Lua documentation with ldoc à la doxygen, I was able to resurrect the original usage of ldoc in the build process but I'm not sure about it. ldoc depends on Penlight which in turns depends on LuaFileSystem. ldoc and Penlight are pure Lua but LFS is a C module.

Nominal usage is having the user install Lua on her PC, then install LuaRocks (a Lua package manager) and then install the modules/dependencies with it. LFS being a C module, you need to have a compiler properly defined so LuaRocks can compile the C stuff on the fly during installation. I'm not a fan of this, I prefer having all the tooling available in the git repo directly instead of depending on package managers fetching who knows what off the internet. Also I don't know how to do this on github CI.

As a result the current solution is done with vendoring LuaFileSystem, Penlight and ldoc in the Extern directory. None of the 3 provide files for cmake integration so that's an added difficulty.

I'm really not good with cmake and will probably need help in making a clean integration of this in the build chain.

It looks like the Lua version we're using is the [really] old 5.1, ldoc crashes with it. I had more success with the 5.1.5. Since it's included as a submodule, I'm not sure how to do a PR to upgrade it. Also the repo it was forked from does not provide a 5.1.5 tag, that's an additional problem...

That being said, the generated doc is quite out of date compared with the hardcoded HTML one (skp is not described for example), but updating it is really easier than messing with the HTML manually so it should not take that long to have it updated.

I'm attaching a sample with this PR so you can see what it looks like : orbiter_lua.zip

Edit : Looks like ldoc did not crash in CI, hooray...

jarmonik commented 7 months ago

Noticed some problems with page width, code example boxes and equations but otherwise it looks good to me.

TheGondos commented 7 months ago

Some more work on this ; there should be one more iteration with content and then a final pass for corrections.

For reference, it looks like the ldoc crash happens when there is no empty line between a ':' and a following list of elements :

 crashme:
 - a
 - b

This triggers an assert 100% of the time in debug builds, Sample: orbiter_luadoc.zip

TheGondos commented 6 months ago

ldoc is returning an error I can't reproduce on my side :( Don't know if it's a dependency issue or if the program crashes, there's not much logs to investigate. Is it possible to run an interactive session? Edit: it was indeed a crash, the same as mentionned before but in release build this time. This ldoc stuff is a real house of cards... Did a forced push to cleanup the mess I made while investigating. Latest sample: orbiter_lua.zip

TheGondos commented 6 months ago

Squashed everything, there are probably still some corrections to make but I think it's ready for merge.