Renoise Lua API Reference (pretty html)

Renoise Tool Development
1

A pretty HTML version of the Renoise Lua API can be found here:

http://files.renoise.com/xrnx/documentation/

It’s also contained in the StarterPack download:

http://code.google.com/p/xrnx/downloads/

How it was created:

I’ve been working at reformatting (and proofing) the API Documentation in combination with writing a PHP script that converts them to HTML.

The api_to_html script is in SVN:

https://code.google.com/p/xrnx/source/browse/trunk#trunk%2FXtra%2FHtmlGen

The process of conversion involves running a series of hacks and regular expressions to end up with something parse-able by PHP Markdown and GeSHi. The design is pure CSS.

Cheers.

2

Definately!
An index with clickable bookmarks (TOC) is also very welcome if possible.

3

In the main index? Or at the top of each file? Or both? It’s a good idea though I’ll look into it.

I’ve updated the docs and the code to generate them. I’ve changed the output so that the code is syntax highlighted (using GeSHi):

[s]> http://www.trotch.com/tmp/api_to_html-alpha-version_02/[/s]

Is this better?

I have a few more days of proofreading to do, but I’m getting somewhere.

Cheers.

4

This is great Conner!

Personally I find the yellow hilighted version easier to read as the beigey text in the second seems a little washed out.

maybe an amalgamation of the two, still including syntax would be best?

5

Thanks.

Because of the way GeSHi formats the code, I can’t get the exact same behaviour as in v1. But CSS tweaking is certainly possible and I’ve tried to do an amalgamation, like you suggested, for version 3 below:

[s]> http://www.trotch.com/tmp/api_to_html-alpha-version_03/[/s]

I think it’s pretty good?

In any case, it’s CSS so I can always tweak this after. Right now the CSS injected but once I’m near completion it will be a shared CSS file. I’m just lazy at the moment.

Thanks for the feedback so far vV and Ledger.

6

Yes i meanted the latter.
The index itself already existed, the references in the file itself does not, but that would probably mean to index based upon the header type of functions mentioned i guess.

It is looking good, i like the v3.0 version as well.

7

Yes, looking good,

If possible the icing on the cake would be the reserved word colours matching the renoise ones etc.

8

Me too. Looks and reads just great!

9

Alright,

At this point I will say that I’ve reached “version 1” for this effort and it’s done.

@see: http://trotch.com/tmp/api_to_html-v1/

I’ve also attached a packaged version that you can install locally. Taktik will be putting it up in a more official manner in the upcoming days.

Thanks for the feedback.

Enjoy.

10

This looks like the proper guided API documentation i’m used to… .I’m proud of you! :)

11

I changed the way the index is generated.

I moved the attachment into the first post.

Cheers.

12

HTML docs were moved to the StarterPack:

Done!

13

Been doing some scripting, the documentation is pretty good! For future updates, can we please get a basic search feature? Or I’d even take all APIs in a single html file, so it’s all ctrl+f searchable. Song.API is the the main and largest one, but sometimes you want to check something in the other parts of the API and then have to go back to the index, figure out which one to open, etc.

14

I would like to suggest a little better structured documentation… :stuck_out_tongue:

IMHO even using this “pretty-html” version, it’s still a pain in the ass to use it.

I basically miss a staying menu/navigation on the left, and a method index. Even a javascript search would be completely overdope. I mean really documentation standards that where introduced around the early 90’s…

EDIT:

And cross linking would help, too :slight_smile: Like, return type is “-> [array of renoise.PatternLine objects]”, <- then clickable "renoise.PatternLine"with a link to that definition.

The navigation could consist of the method index in openable/closable sub-nodes / in a tree structure.

15

A pretty HTML version of the Renoise Lua API can be found here:

http://files.renoise.com/xrnx/documentation/

It’s also contained in the StarterPack download:

http://code.google.com/p/xrnx/downloads/

Whereabouts is the HTML in the download? I can only find .Lua files for the documentation.

Should the HTML be generated from the .Lua files somehow?

16

http://files.renoise.com/xrnx/documentation/

But it is outdated, and there is no information, if the Renoise team will add missing points.

17

Thanks got that. I prefer a local copy but I suppose I could ‘mine’ the html.

18

Requires some dev know how:

Clone:https://github.com/renoise/xrnx

Configure and run this script:https://github.com/renoise/xrnx/tree/master/Xtra/HtmlGen

Should still work?

Junky script could be improved using composer packages instead of copy/paste includes dir, contemporary PHP syntax, and so on… Patches welcome.

19

Requires some dev know how: using composer packages instead of copy/paste includes dir, contemporary PHP syntax, and so on… Patches welcome.

Yeah… and perhaps web dev know-how too. I’d be “comfortable” running some command-line stuff on my laptop but “copy to a webserver…”… seems like a bit of a mission.

20

I wish it would update correctly. One of the advantages of having the documentation in HTML is that it is easy to translate all the information into another language (I mean the descriptions). This allows beginners to understand more quickly the API available to create tools, because they are using their language.

Also, I do not like too much how the jump lines are built in the documentation for the terminal (Documentation/ files.lua). For example:

…

renoise.song().artist, _observable

-> [string]

renoise.song().name, _observable

-> [string]

renoise.song().comments[], _observable

-> [array of strings]

…

It seems easier to read vertically like this:

…

renoise.song().artist, _observable -> [string]

renoise.song().name, _observable -> [string]

renoise.song().comments[], _observable -> [array of strings]

…

In HTML you can play better with these things for a more pleasant reading.Help the eyes to locate the desired code faster…