Offline LÖVE documentation for download

General discussion about LÖVE, Lua, game development, puns, and unicorns.
sephoric
Prole
Posts: 3
Joined: Tue Feb 12, 2019 6:25 pm

Re: Offline LÖVE documentation for download

Post by sephoric » Tue Feb 12, 2019 6:43 pm

I just made another thread (pending moderation) that is related to this thread. I had the same issue, that I was having trouble getting offline documentation. And I realized, I already solved this same problem in another programming domain (window manager), where I created a full IDE that had a built-in documentation viewer which was very well received.

I'd like to make the same kind of IDE for Love2d, that has the same kind of documentation viewer built in, among many other features. I'd be willing to do all the legwork to make this as well as to generate the documentation from portions of the wiki. Would anyone be interested in such an IDE? See my other thread for more details.

Santos
Party member
Posts: 383
Joined: Sat Oct 22, 2011 7:37 am

Re: Offline LÖVE documentation for download

Post by Santos » Wed Oct 02, 2019 12:52 pm

I found the URL love2d-community.github.io/love-api a bit hard to remember, so I've updated loveref.github.io

I've also added a note at the top about it being unofficial and incomplete, and instructions on saving it for offline viewing.

Fuzzlix
Citizen
Posts: 59
Joined: Thu Oct 13, 2016 5:36 pm

Re: Offline LÖVE documentation for download

Post by Fuzzlix » Thu Oct 03, 2019 6:31 pm

Great Job. I saved the webpage localy. Its only 1 html file, easy to copy. The layout looks good. You made me happy. :)

Santos
Party member
Posts: 383
Joined: Sat Oct 22, 2011 7:37 am

Re: Offline LÖVE documentation for download

Post by Santos » Wed Oct 09, 2019 9:57 am

Dear Slime, Bartbes, Rude, any other devs, and everyone else in the world,

I'd like to propose to you all (not like that) that you consider using something like love-api as the official documentation for future versions of LOVE.

tl;dr: It means better docs can be generated, and IDEs can use it for auto-completion, but it would require a bit of work (hopefully not heaps though), and the wiki already exists so I can understand why you wouldn't want to bother with this proposed idea.

The pros:
  • More flexibility in how the documentation is presented. loveref.github.io isn't perfect, but it's an example of what can be generated from the LOVE API Lua table, and I prefer it to the wiki because it's fast to navigate due to not having to load additional pages, I like that the setters and getters are listed together, I think it looks cleaner, I like the font that I stole from LOVE's homepage, etc. I don't know if everyone likes it, but my point is that generating documentation from the the LOVE API table gives us flexibility in how we want to display it, and something better to use than the wiki could be created. It would be great to create some mobile-friendly documentation for example.
  • IDE support. The love-api README lists 9 projects using it for code completion for IDEs/text editors.
  • Easier for documentation editors. Edits could be made via GitHub's text editor, and approved before they are merged (I'm not sure if needing to approve changes is a pro or a con). There is less "boilerplate" for adding things to the LOVE API table than to the wiki, for example when adding a function to the wiki one needs to make sure the function name is the same in the page name, the synopsis and the other languages section. Also, the LOVE API table is automatically checked to see if new commits follow the spec. Also, a lot of programmers will already have a GitHub account, and won't need to sign up for a LOVE forums account to make edits.
  • Better support for languages other than English. I would recommend trying to use the wiki in another language to see what the current experience is like. For example, from the main page I click "Português". Then I click "love.graphics", and the page is back in English again. I click "Português" again, and anything that hasn't been translated is missing from the page, and old functions are still there. With the LOVE API table, you can generate documentation using the English descriptions instead of the descriptions in the other language when they aren't available, or what I experimented with was Google translating untranslated descriptions. Because only the descriptions are changed, it means that changing the function (e.g. changing the function name) doesn't mean that you lose the translations. For the wiki to work well in another language every single page would need to be translated and kept up-to-date and I don't think this is feasible.
  • Easier mass editing. I'm not sure how often this kind of thing would occur, but, for example, the color range change from 0-255 to 0-1 could have been (almost) done with a search and replace.
  • You can "query" the LOVE's API, like list the functions that return a boolean, or find out the number of functions LOVE has.
  • It allows the documentation to have its own issue tracker, which I think would be quite useful.
The cons:
  • There is some stuff that the LOVE API table doesn't currently do but could do fairly easily I think, like support images (images can be uploaded to GitHub), example code and internal and external links (the internal links, like descriptions linking to functions, in loveref.github.io are automatically generated). Some markup would need to be created.
  • There also isn't information about which LOVE versions things were added/removed in, which I also don't think would be difficult to add, but I'm not sure if it's absolutely necessary, as long as there is a version of the documentation for each LOVE version. But, it is nice to know what a renamed function for example has been changed to (LOVE's deprecation output helps in this regard).
  • The wiki allows for more freeform editing, which the PixelFormat page makes use of. There could be some structure added to the table to make this kind of page possible, or it could just be linked to externally, but I can understand that when adding documentation you probably don't want to be thinking about how it can be added within the structures the table has or what new structures need to be made.
love-api already exists, but unless it's the official thing that the devs update, I don't think it can be trusted as a source of accurate and up-to-date information, which makes it not very useful, and not very motivating to work on.

In other news, love-api, love2d-community.github.io/love-api and loveref.github.io have been updated to 11.2, thanks to scraping the wiki (thinking that this used to be updated by manually copy and pasting makes me... uncomfortable). The HTML references also have a "dark mode" if your OS/browser supports that (thanks to codyloyd on GitHub).

And thanks Fuzzlix! :)

And also huge thanks to Slime for not only developing LOVE but for keeping it so well documented! :)

adamto99
Prole
Posts: 1
Joined: Tue Nov 12, 2019 12:45 pm

Re: Offline LÖVE documentation for download

Post by adamto99 » Tue Nov 12, 2019 12:46 pm

Fuzzlix wrote:
Thu Oct 03, 2019 6:31 pm
Great Job. I saved the webpage localy. Its only 1 html file, easy to copy. The layout looks good. You made me happy. :)
Going to have to code offline too! :P

Post Reply

Who is online

Users browsing this forum: No registered users and 8 guests