Local-based documentation

[awilliamson]

@EpicG and I have been discussing the benefits of a local-based documentation system, hinging around the extensibility point of view.

Many people, if they modify their SF instance from stock, won't get documentation for their addons. If the local user wishes to generate documentation they would need to install the LuaDoc module and run it on their system, having been told the command to use. This is exceptionally burdening for the user, especially the less technically capable and makes SF less accessible as a result. It could be argued that it is up to communities, or library creators to document their additions; however, this then fragments the documentation and reduces the usefulness of the SFHelper from within game, from a use-case viewpoint.

I feel that it may be possible to move/port LuaDoc from the system domain to the GMod domain. Provided GMod allows the amount of access we require from system libraries of Lua ( files etc ). This does mean that the codebase would be a little more bloated, but would make the SFHelper as robust as possible considering we wish to have an extensible framework, in differing environments: Communities stock, communities custom, singleplayer, singleplayer no internet custom, etc...

Would love some input from @Xandaros, @Jazzelhawk. I understand the 'HCI' viewpoint may be tiresome, but @EpicG raised some good points that I can't really dispute. "The community should host them" doesn't exactly work as a valid excuse for all cases.

[davidsonbr]

An idea just popped into my head that will most likely sound extremely dumb once I finish typing it out. I'm going to do it anyways.

What I'm thinking of is a seperate addon that can be bundled to work with starfall. The addon would be installed on a server / client that wants to generate the documentation into the JSON based documentation that I have been working on ( here ).

When the server starts it would check to see if the documentation has already been generated ( maybe keep a file of libs that have been documented or concmds to redo documentation of everything / certain libs ). If not, it will go through all the files similar to LuaDoc and parse the documentations into the JSON format that I described previously.

With this it would allow for the existing LuaDoc system for online documentation, as well as support for sf helper that does not require internet / the server admin to make a custom version of LuaDoc to have all of their SF addons documented.

Read through that again. Sorry if I made your eyes / brains bleed.

[Jazzelhawk]

I think having the documentation generator part of the main addon instead of another addon would be best since it would mean documentation could be generated at any time for anyone. Where as if it were a different addon it would be difficult to know when to switch the SF Helper between sf.inp.io/doc.json ( or communities version ) and local/server files. If it were part of SF then it could generate the documentation on server startup ( including singleplayer ) and just use the files generated from that.

If @awilliamson intends to remove LuaDoc completely then I think a good solution would be to have the JSON documentation as @EpicG pointed out which SF Helper can then interpret and display but then also have another generator for turning the JSON files into a web based documentation for the communities who wish to have it hosted online.

A lot would have to be changed with SF Helper to support the new documentation format and would also mean sending lots of files from serverside to clientside and the editor already does enough of that with the ace files.

[Xandaros]

Having doc generation baked into SF is a good idea. It would still require third party developers to write documentation, though, there's no way around that. (I looked, as far as I can tell, you can't get the name of parameters of a function. Unfortunately :/)

If we make it modular enough, it might serve as generating both JSON and HTML. You could then call it from within SF to generate the JSON (probably cache it for everyone's sanity) and from outside to generate the HTML.

[davidsonbr]

To prevent sending the files every time a player connects to a server, we would have to store it in data being that is the only place we can write to in-game. As long as comments are sent when AddCSLuaFile is called, we will be able to parse through them to make the JSON / HTML files

data/starfall_doc/json data/starfall_doc/html

Only problem with that is when the player joins another server that has a different version of SF. More / less libs would not be a problem as they would not have to be loaded when the library itself is not loaded.

[Xandaros]

Well, I was thinking of caching them in memory, but writing them to disk would certainly work. However, if you don't want to regenerate them on each server start, you'll have to figure out a way of detecting changes. (Otherwise, what's the point of storing them on disk?)

If we do save it to disk, though, it would allow the game to generate HTML and could get rid of the external doc generator. However, that would also mean generating all of the HTML stuff yourself, without using existing libraries to do that for you. (I haven't looked at the doc generator in a long time, not sure how easy it would be to replicate)

[davidsonbr]

If we do decide to use the new library hierarchy that I am working on in my permissions-overhaul then it would be easy to see what libraries the user has or does not have.

We could add a version tag to the library.json and have the documentation saved for that specific verison. Could potentially create a bunch of files which isn't good.

Documentation being saved per lib version it would be easy to automatically prune the old versions if they have not been used in X days.