Unfortunately I think the main blocker on including love2d documentation is that the existing sources of documentation data are licensed incompatibly with fennel-ls. (GFDL 1.3) There has been some discussion of workarounds for this, but it would probably mean that the love2d doc set is either distributed separately, or auto-generated by the user rather than being built-in to fennel-ls. =(

Yeaaaah, lol. I only figured that out once I already did the work here to pull down love2d-community/love-api and parse it for fennel-ls. Technically that repository doesn't have a license, but given that GFDL requires the derivative works are licensed using the same one, we have to assume that it carries the same license, right? I wonder if slime would ever change the Wiki license, but for now, is this the best way forward?

1. Make a new repo, e.g. fennel-ls-love-2d
2. Pull all of my work into that repo
3. Link to it in fennel-ls if folks are interested

I'm cool to abandon the work too, but I'm close enough that I thought I'd try. :D

Yep, the contents of love-api have to be GFDL, even tho they fail to declare it in their repository.

Personally I think the best way would be for fennel-ls to be able to be pointed to a checkout of love-api and generate a docset from that, either on the fly directly in memory, or written out to disk somewhere it can be loaded up again later without regenerating it. If we do the latter, perhaps there could be a directory where docsets can be loaded from which could also be used to store docsets from other 3rd-party APIs.

However, I don't think your own work should be blocked by needing to create a docset-path! So maybe that first option of parsing it afresh from a checkout every time the server runs in a love2d project would be a good first start. I guess the main question about that would be how to know where to find the love-api checkout on disk. I'd say for now just hard-code it to wherever it is on your system and we can figure that out later.

Does that make sense?

Personally I think the best way would be for fennel-ls to be able to be pointed to a checkout of love-api and generate a docset from that

Perfect! Incidentally, that's pretty close to what I did. :)

If we do the latter, perhaps there could be a directory where docsets can be loaded from which could also be used to store docsets from other 3rd-party APIs.

This makes sense to me. A ~/.config/fennel-ls/docsets path or something?

Does that make sense?

It does. Right now, this is what I have written:

1. When tools/get-docs.fnl runs, clone the love-api repo into build/
2. love-api docs are parsed into src/fennel-ls/docs/generated/love2d.fnl
3. love2d can be passed as a library in the config and this doc will be added.

If I understood you correctly, these are rough next steps:

1. Remove this clone step, refactor tools/get-docs/love2d.fnl to take the repo directory as an argument, so it can be run manually.
2. Submit this as a PATCH, with love2d only supported if you compile fennel-ls yourself.

(Optional, with a lot of hand-wavy naming and architecture thoughts haha)

1. Add a config option for :docsets-path, default to ~/.config/fennel-ls/docsets (or whatever)
2. Add a --parse-docset flag to the CLI that takes a repository path, then a parser pattern matches to user/repo-name (or two separate arguments, path and parser), and exports the parsed docset to the configured docset path.
3. Submit as a PATCH.

Is this in the ballpark for what you were thinking?

EDIT: Also, I forgot to mention that architecture wise, I ignored all of the variations and only picked the first one. You miss out on some of the consolidated function calls, but that's good enough to start I think.

I guess just to make it a bit clearer:

• We do want code to convert the data in love-api into a format that fennel-ls understands
• We can't include the converted data as part of fennel-ls
• We could (and probably should?) include the code to do the conversion
• We could (maybe in a future version) include code to auto-download love-api but let's start with the assumption that a checkout exists on disk for now

edit: oops I didn't see your reply when I posted this; let me take a closer look lol

If I understood you correctly, these are rough next steps:

1. Remove this clone step, refactor tools/get-docs/love2d.fnl to take the repo directory as an argument, so it can be run manually.

Oh lol I didn't realize you already had it cloning; nice. This is great. Maybe instead of removing it, you could make it optional based on an environment var so you have to run LOVE2D=y make fennel-ls when compiling to get the love2d docs in a way that wouldn't include them in the "official" release.

• Add a config option for :docsets-path, default to ~/.config/fennel-ls/docsets (or whatever)

This sounds great.

• Add a --parse-docset flag to the CLI that takes a repository path, then a parser pattern matches to user/repo-name (or two separate arguments, path and parser), and exports the parsed docset to the configured docset path.

So you'd run something like fennel-ls --parse-docset https://github.com/love2d-community/love-api and it could clone the URL given and write the extracted docset to the docset-path? And then you're saying that for starters it would look for the love-api pattern specifically and that would be the only one supported, but we could extend it in the future to support other libraries?

I think that sounds pretty good! It's possible the extensibility of the URL is overkill, because it might be kind of unlikely that other libraries will have licensing problems with their data, but it's not a bad idea. Let's see what Xero says.

Sorry this is so complicated =)

Thanks for getting back to me!

Now that you mention it, the CLI flag is definitely overkill, haha. My hope was to enable folks who download fennel-ls through a package manager a way to run a stateful command that generates the documentation on the fly in a straight-forward way rather than needing to manually build.

So I agree with you on the env approach; it's easier, and you should only have to build the Love documentation each Love update. I'd probably do that by running the script manually outside the package anyway to start. If we wanted to expose that functionality in a more automated / user-friendly way, then it makes sense to think of the abstraction more holistically, e.g. a plugin architecture, rather than how do we get around a license, haha.

I'll wrap this up with this assumption in mind since a patch gives us something concrete, but I'll change whatever should we need a different approach!

Thanks for putting this together! I pulled it down to try it, and made a few minor adjustments but then it seemed to work well for me from Emacs:

https://git.sr.ht/~technomancy/fennel-ls/log/eb/add-love2d <- feel free to incorporate any of these changes, either as the whole patch or just piecemeal

I'm not the maintainer of fennel-ls so I'll let Xero have the last word on this, but he might prefer it without the autoformatting changes like the changes from "build/" to :build/.

Thanks a lot for taking the time! I appreciate you.

I merged your change, then went back through and removed all of the accidental fnlfmt changes and renamed some stuff, so I think this is good to go as a starting point!

For posterity, I added the git clone util because I saw it used elsewhere, but I didn't refactor any of those spots so this change could be smaller; happy to change that if I need to though.

My email provider doesn't have SMTP access so I'm not quite sure how to do git send-mail just yet, so I just pushed it up here:

https://git.sr.ht/~emlabee/fennel-ls/tree

I'll try and figure out how to submit a PATCH. If it's helpful to pull anything from that repo directly, then I'm also happy to rebase the history and either squash into one commit, or into smaller logical ones. Let me know if either of you have any feedback or need anything else from me here!

No need to submit as a patch; I'll merge it right now.

Expect a bit of code churn before this code makes it to a release: I want to make sure that fennel-ls can also detect the love-api.love_api module on the path at runtime, if the docs aren't built in. My plan is basically to promote the love2d code from tools/ to src/fennel-ls/docs/.

Looks like this landed; will close this out. Thanks! lmk if there's anything remaining to discuss.