Re: [ZeroBrane Studio] Library documentation

[Paul K <paulclinger@...>]

Hi Jay,

> I tried looking at the code of ZBS to see if, I could add a link in the 'Help' menu to open this documentation up, in a local directory on my PC. Couldn't make much headway so far.

This is possible; see below.

> I plan to write a meta-index, that will have short description of the library, and then links to open-up whatever documentation, in whatever form is available, which could be HTML doc-set, README, sample / test lua files. If it is README, it'd be rendered as-is in the browser, but if Lua code (Sample/test), then I plan to have the lua-code displayed via HTML-beautifier !
> Do you suppose this might be useful ?

I definitely think so. It's not immediately obvious what the best way
to distribute this documentation would be though. LuaDist already
includes Documentation section in its "files" description and those
documentation files can be deployed for local access. Many library
authors already use Steve's LDoc, which can be rendered as html; see
for example, excellent documentation for Steve's Penlight:
http://stevedonovan.github.io/Penlight/api/topics/01-introduction.md.html

> But then again, based on an exchange with Peter Drahos, I get the impression that ZBS would be included in LuaDua at somepoint in future (perhaps before the user-conf),

Do you mean LuaDist here? ZBS is already included with LuaDist as one
of the modules, but the idea we discussed was to integrate LuaDist
with ZBS to allow ZBS users to easily get access to Lua modules and to
install them from LuaDist. The bootstrap modules would come
prepackaged with ZBS and would allow users to type into Local Console
in ZBS:

> luadist.install('lpeg')

and after that "require('lpeg')" just magically works (both in the
console and in the scripts).

I already got it working on Windows and am working on adding OSX
support. It would be interesting to include documentation support as
well, so that luadist.help('lpeg') would install/show lpeg
documentation if available.

> PS> In any case, I'd try to make this change in ZBS locally, to try it out. If you can point me to the source file, where I might add a new menu-item under 'Help' and then add the URL to local index.html file, it'd be great.

Try this plugin. Save it into packages/localhelpmenu.lua. You can
specify the index reference by adding "localhelpmenu = {index =
[[D:/path/to/index.html]]}" to ZBS config.

local G = ...
local id = G.ID("localhelpmenu.localhelpmenu")
local menuid
return {
  name = "Local help plugin",
  description = "Adds local help option to the menu.",
  author = "Paul Kulchenko",
  version = 0.1,

  onRegister = function(self)
    local menu =
ide:GetMenuBar():GetMenu(ide:GetMenuBar():FindMenu(TR("&Help")))
    menuid = menu:Append(id, "Lua Documentation")
    ide:GetMainFrame():Connect(id, wx.wxEVT_COMMAND_MENU_SELECTED,
      function (event) wx.wxLaunchDefaultBrowser(self:GetConfig().index, 0) end)
    ide:GetMainFrame():Connect(id, wx.wxEVT_UPDATE_UI,
      function (event) event:Enable(self:GetConfig().index ~= nil) end)
  end,

  onUnRegister = function(self)
    local menu =
ide:GetMenuBar():GetMenu(ide:GetMenuBar():FindMenu(TR("&Help")))
    ide:GetMainFrame():Disconnect(id, wx.wxID_ANY, wx.wxID_ANY)
    if menuid then menu:Destroy(menuid) end
  end,
}

On Fri, Oct 25, 2013 at 12:37 AM, Jayanth Acharya <jayachar88@gmail.com> wrote:
> Paul,
>
> Being a Lua newbie, learning it in my spare time, and coming from a
> background of some exposure to Python, Erlang -- I found Lua's lack of
> organized (in one place), documentation of libraries, to be quite a bit of a
> handicap in my learning & experimentation.
>
> So, I spent couple of hours to download library documentation of about 90%
> of libraries in LuaDist, which could be in form of HTML file, or plain text
> README, or just sample lua code, and created a sort of documentation
> snapshot.
>
> I tried looking at the code of ZBS to see if, I could add a link in the
> 'Help' menu to open this documentation up, in a local directory on my PC.
> Couldn't make much headway so far. While I'm yet to do it, but I plan to
> write a meta-index, that will have short description of the library, and
> then links to open-up whatever documentation, in whatever form is available,
> which could be HTML doc-set, README, sample / test lua files. If it is
> README, it'd be rendered as-is in the browser, but if Lua code
> (Sample/test), then I plan to have the lua-code displayed via
> HTML-beautifier ! Do you suppose this might be useful ?
>
> But then again, based on an exchange with Peter Drahos, I get the impression
> that ZBS would be included in LuaDua at somepoint in future (perhaps before
> the user-conf), and in that case, the duplication of documentation might be
> wierd, and anyhow, there is no way to keep the documentation snapshot
> in-sync with evolutions in the library. Is there a better way that ZBS could
> take care of this, systematically ? I still don't know enough of Lua to make
> a well-informed call on this.
>
> Jay
>
> PS> In any case, I'd try to make this change in ZBS locally, to try it out.
> If you can point me to the source file, where I might add a new menu-item
> under 'Help' and then add the URL to local index.html file, it'd be great.