Building LUA documentation using NaturalDocs 2.x (Linux)

[clausimu]

Building the LUA documentation locally is pretty simple. In case you want to use the (currently unsupported) NaturalDocs v2.x in Linux:

1. install mono ("mono-devel" package for openSUSE)
2. download NaturalDocs from https://naturaldocs.org/download/ and extract
3. create the following folders (or any others where the documentation and the NaturalDocs project files should go):
   
   • /path_to_your_pioneer_folder/naturaldocs
   • /path_to_your_pioneer_folder/naturaldocs/docs
4. run from command line:

Code: Select all

mono NaturalDocs.exe -i /path_to_your_pioneer_folder -o HTML /path_to_your_pioneer_folder/naturaldocs/docs -p /path_to_your_pioneer_folder/naturaldocs

edit:
Standard NaturalDocs does not recognize the "Attribute" keyword used in the pioneer lua files. To include documented attributes/variables in the local lua reference you need to edit (or place a new) Comments.txt into the project folder (/path_to_your_pioneer_folder/naturaldocs) that includes:

Code: Select all

Code: Select all

Alter Comment Type: Variable

   Keywords:
      Attribute
      Attributes

[Gliese852]

Thanks! This may be useful for me to build the documentation into an rpm package for Alt Linux. It is a pity that naturaldocs is not very common (especially version 2.x). Apparently no one really wants to have mono in build dependencies.

[impaktor]

Code: Select all

<sturnclaw> NaturalDocs 2.0 is the version we will support moving forwards -
            it works fine, just needs a build script/CMake target and
            associated CI workflow to build and publish [04:30:54]

So, we just need to update above, and COMPILING.txt, if anyone is feeling up to it.

(Doing the CI workflow falls on my table, I guess. I'll see if I can see how it currently (doesn't) work).

[clausimu]

script/CMake is a bit out of my comfort zone...

[impaktor]

I'll see if I can harass someone to fix the CMake for us.

[impaktor]

Well, turns something came out of this Saturday's 'knoting' (Norwegian word, roughly: tinkering)
https://github.com/pioneerspacesim/pioneer/pull/5575

[impaktor]

For completeness, this issue is solved, we now have auto-generated code documentation that will always be up-to-date with master:
https://codedoc.pioneerspacesim.net/

If anyone have Natural Docs config suggestions, please let us know.