Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Sign In Register

Categories

In this Discussion

Two Lives Left on Twitter
Two Lives Left on Facebook
Codea Wiki
Codea Development on Twitter

Is the documentation online somewhere?

Andrew_StaceyAndrew_Stacey Mod
edited December 2011 in Wiki Posts: 2,161

If not, could we put it somewhere?

If there isn't an obvious other place, it could go on the wiki. I realise that the current format is probably not suitable for just cut-and-pasting, but it's probably nothing a decent perl script couldn't fix ...

Comments

  • SimeonSimeon Admin Mod
    Posts: 5,778

    http://twolivesleft.com/Codea/Reference - please note it only works in Webkit browsers. We can make the raw JSON source available if anyone wants to feed that into a different front-end.

  • BortelsBortels Mod
    Posts: 1,557

    yes please - I use chrome habitually. Meant to mention this long ago, slipped my mind.

    Is there some reason it shouldn't be viewable with any browser???

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Chrome is a Webkit browser, it should work in Chrome.

    The reason it's not viewable in any browser is because it uses the Sencha Touch JS framework, which is designed mainly for iOS and Android.

  • BortelsBortels Mod
    Posts: 1,557

    Yep, no luck. With multiple versions.

    If we must be gadgety with a web ui (I admit bias - I'm old school, if it doesn't fallback to at least render text inall browsers - even ie - I wouldnt put it up - especially not simple documentation) - can we at least have an alternate URL with plain old HTML or even just ASCII text? My iPad displays that fine as well.

  • NatNat
    Posts: 143

    Yeah. I use Linux usually so having the API docs open in Chromium on my laptop while Codea is open on the iPad would be really handy.

  • BortelsBortels Mod
    Posts: 1,557

    "Uncaught TypeError: Property 'scrollTo' of object [object DOMWindow] is not a function" and you get a blank page. Boo on sencha for no fallback. To be fair, I guess it is an application framework.

  • SimeonSimeon Admin Mod
    Posts: 5,778

    It's only using the Web UI because it's designed to be displayed in-app from the keyboard popup, not really in a separate browser.

    The best we can do is make the current JSON description available online for feeding into a different HTML output. I'll look at doing that tomorrow.

    Odd that it doesn't work in Chrome though. It works in Chrome (Mac OS X) here. I thought Chrome rendered the same cross-platform.

  • BortelsBortels Mod
    Posts: 1,557

    I'd suggest you put the raw text (or an html render) into the wiki. That way bugs, comments, and example code could go in right alongside.

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Good idea. The text is a bit unwieldy as it's a nearly ~3000 line chunk of JSON.

    This source is actually available here: http://twolivesleft.com/Codea/Reference/app/stores/reference.js

    I'm happy to take suggestions on what to do with it.

  • BortelsBortels Mod
    Posts: 1,557

    heh - just the direct reference is good for the short term - I can display that page and search.

    In the spirit of "Never have the devs do something we can do (and so allowing the devs to work on Codea itself", I suggest you do nothing; we have the json. I may spend an hour and write a renderer that dumps it as wiki markup (or if I delay too long, someone else likely will), and then post it to the wiki, depending on if my wife and kids allow me a moment of peace. :-)

  • BortelsBortels Mod
    Posts: 1,557

    sigh...

     bortels@duo:~/dev/codify$ curl http://twolivesleft.com/Codea/Reference/app/stores/reference.js
<html>
<body>
<h3>This browser is unsupported. Please use a webkit browser such as Google Chrome or Apple's Safari</h3>
<body>
</html>

    No big deal, used chrome to save it, but really - nothing should be checking browser type to simply download a javascript file. (My idea was to make a script that would dynamically fetch/translate the source, so that changes there would reflect in the new version automatically...)

  • BortelsBortels Mod
    Posts: 1,557

    ack - it is also not actually JSON (it's simply javascript). Even removing the wrapper around it, the multiline entries with "+" at the end aren't valid JSON - simply meaning this isn't quite as simple at throwing it at a JSON parser then spitting out the data structure.

    maybe I'll just cheat and "eval" it in node.js :-)

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    Firefox's user agent switcher comes to the rescue! One of the ones that I have installed (must be by default as I don't remember installing it) is iPhone 3.0. Whereupon, I get the code.

    On a serious point, when I first heard about Codify then I went to look at the documentation to get an idea of whether or not it would be suitable for what I wanted to do. Not being able to see the documentation meant that I initially dismissed it. It was really only the distinct lack of anything else out there that meant that I reconsidered it (it was either Codify or CBM64 Basic!). So the code documentation really, really ought to be readable anywhere.

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    And then I wonder why the forum suddenly looks very different ... time to switch the user agent back to something sensible.

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    I made a start at:

    https://bitbucket.org/TwoLivesLeft/codea/wiki/Documentation

    I downloaded the file linked above, did a small amount of pre-processing:

    cat documentation | perl -lne 's%//.*%%; s%(^\s*)(\w+): *%$1"$2" => %; s%^\s*$%%; s/\+\s*$/. /; $_ and print;'

    Modulo a bit of junk at the start, this turned the data structure into a perfectly valid perl data structure. The start needs to look like:

    $doc = {'Reference' => {
    "model" => 'Library',
    "data" => {"libraries" => [
           {

    which means that the end has to read:

        "proxy" => {
        "type" => 'memory',
        "reader" => {
            "type" => 'json',
            "root" => 'libraries'
        }
    }
    }};

    The rest of the code (which is highly hackish) is:

    foreach $library (@{$doc->{"Reference"}{"data"}{"libraries"}}) {
    print &header(3,$library->{"name"}) . "\n";
    print &header(4,$library->{"subtitle"}) . "\n";
    foreach $fn (@{$library->{"functions"}}) {
    print &header(5,$fn->{"name"}) . "\n";
    if (defined $$fn{"examples"}) {
        $numexs = @$fn{"examples"};
        $title = "Example";
        if ($numexs > 1) {
        $title .= "s";
        }
        print &header(6,$title) . "\n";
        foreach $example (@{$fn->{"examples"}}) {
        ($e = $example->{"example"}) =~ s/\\n/\n/g;
        $e =~ s/\\t/\t/g;
        print &code($e) . "\n";
        }
    }

    print &header(6,"Description") . "\n";
    ($d = $fn->{"description"}) =~ s/\\n/\n/g;
    print &paragraph($d);
    if (defined $$fn{"syntax"}) {
        print &header(6,"Syntax") . "\n";
        ($s = $fn->{"syntax"}) =~ s/\\n/\n/g;
        print &code($s);
        print "\n";
    }
    print &header(6,"Parameters") . "\n";
    print "\n";
    print &tableHeader("Name","Description") . "\n";
    foreach $parameter (@{$fn->{"parameters"}}) {
        print &tableRow($parameter->{"name"},$parameter->{"description"}) . "\n";
    }
    print "\n";
    if (defined $$fn{"returns"}) {
        print &header(6,"Returns") . "\n";
        print &paragraph($fn->{"returns"});
    }
    if (defined $$fn{"related"}) {
        print &header(6,"Related") . "\n";
        foreach $related (@{$fn->{"related"}}) {
        print &list(&link($related));
        }
        print "\n";
    }
    }
}

sub header {
    my ($level,$text) = @_;
    return ("=" x $level) . $text . ("=" x $level);
}

sub paragraph {
    my ($text) = @_;
    return "\n\n" . $text . "\n\n";
}

sub code {
    my ($code) = @_;
    return "\n{{{\n" . $code . "\n}}}\n";
}

sub tableHeader {
    return "|=" . join("|=", @_) . "|";
}

sub tableRow {
    return "|" . join("|", @_) . "|";
}

sub link {
    my ($link) = @_;
    my $anchor = lc($link);
    $anchor =~ s/ /-/g;
    return '<a href="#!' . $anchor . '">' . $link . '</a>';
}

sub list {
    my ($text) = @_;
    return "\n# " . $text;
}
  • Ipad41001Ipad41001
    Posts: 622

    Great start, I had given up :)

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Wow forgot about the concatenation - sorry guys. Awesome little conversion, Andrew.

  • BortelsBortels Mod
    Posts: 1,557

    Ha! Andrew wins the "perl king" award for the day. I was about halfway that far when my 16-year-old informed me there was no possible was I could whip him in Age of Mythology, and, you know... Priorities.

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    Fortunately my kids a bit younger and just want to monopolise the iPad to see if they've managed to cross-breed a crocodile with a giraffe yet. So the main computer was free for a bit of perl.

    I meant to break it down into smaller pages. I thought to check out the source via git and use the perl script to output separate pages, but I couldn't get the checkout to work so I gave up on that.

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    Just spotted that the links to other anchors didn't work. Bother.

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    I've updated the documentation to the latest version. I also took the opportunity to fix the embedded HTML (sadly the wiki doesn't take HTML as input, only its own formatting). The links to other anchors still aren't right, sadly, but hopefully it won't take too many more iterations before I figure out the right syntax.

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Thanks for keeping it up-to-date, Andrew.

  • ZoytZoyt
    Posts: 2,820

    Great! Thanks! Two suggestions:
    1. The formatting has problems when viewed on an iPhone.
    2. Keep a beta version for the beta functions of Codea for the curious one and those who want to start coding early.
    3. Change the header from "Codify" to "Codea".
    I use it all the time!
    Thanks!

  • ZoytZoyt
    Posts: 2,820

    Hey, if possible, please make it so it works on an iPhone screen size without getting messed up. And possibly add a version with beta functions in it.
    Thanks!

  • Ipad41001Ipad41001
    Posts: 622

    Does http://twolivesleft.com/Codea/Reference work well enough on the iPhone?

  • ZoytZoyt
    Posts: 2,820

    This is not going to cut it for me @Ipda41001:
    1
    2
    3

    This happens on most pages.
    Thanks!

  • oboudouoboudou
    Posts: 13

    Il would like copi and past code from this help. I am dyslexique and it s very dificul to copy a code with out mistake.

  • Ipad41001Ipad41001
    Posts: 622

    An old copy is here https://bitbucket.org/TwoLivesLeft/codea/wiki/Documentation

  • Andrew_StaceyAndrew_Stacey Mod
    Posts: 2,161

    Hmm, I should update that to the latest version.

  • russmrussm
    Posts: 4

    FYI, I've put together a tiny page that grabs the live online docs and displays them as real JSON for further parsing - http://slofith.org/projects/codea-ref-as-json.html

    you need to be using a WebKit browser since the origin server still does User-Agent sniffing... :(

  • SimeonSimeon Admin Mod
    Posts: 5,778

    Great work @russm. That's pretty handy.

  • russmrussm
    Posts: 4

    ah, man... OK, so the next step (processing the data into plain HTML) is going to be a huge PITA since there's additional pure-js logic in app/models/reference.js for display formatting... and I don't think I can be bothered re-implementing enough of the sencha touch framework to do it... oh well...

  • thomastraumthomastraum
    Posts: 2

    Sorry guess from what was said in the the thread not much of a chance, but has anyone found a way to view the documentation in a desktop browser? doesn't work for me in chrome or safari either. Is json the only option? . I bought the app but much more interested in the runtime now and want to built apps on the desktop.

  • mpilgremmpilgrem
    Posts: 489

    I use Chrome on a Windows 7 system. The version of the in-app documentation here works for me. To scroll, click and dragging with the mouse replaces swipes on the iPad.

  • thomastraumthomastraum
    Posts: 2

    @mpilgrem thanks so much, that works! Sometimes its the simple things... Sorry am on a trackpad most of the time (even though click and hold works on a trackpad too anyway)

Sign In or Register to comment.