Hammerspoon web server and local documentation

[asmagill]

I am working on a more-or-less standards compliant web server wrapper for `hs.httpserver` with cgilua-like template support for lua files... originally I had no real plans to suggest its inclusion in core, since I mainly intended it as a way to view documentation for things that were provided as html files, but the lua template support has reached the point where it can dynamically generate Hammerspoon module documentation from the json file included with the application.

It's still in need of documentation, doesn't fully support POST for the lua templates yet, and has a *very* minimalistic Markdown conversion support (it will use an external converter, if available, but this introduces a noticeable slowdown) -- the built in support basically does some string substitutions to render things more or less in <pre></pre> and <code></code> blocks so it's readable, but it definitely needs work.

With a few additions to the basic example, `hs.webview` could be used to provide a fully integrated, no external software required documentation component to Hammerspoon... what are the thoughts on adding this to the core application?

If anyone wants to take a look, check out https://github.com/asmagill/hammerspoon_asm/tree/master/hsminweb, but be warned, it's still evolving, so some syntax/functionality may change a little.

--

A-Ron

[Chris Jones]

Hey

> On 20 Apr 2016, at 20:53, asmagill <asma...@icloud.com> wrote:
> With a few additions to the basic example, `hs.webview` could be used to provide a fully integrated, no external software required documentation component to Hammerspoon... what are the thoughts on adding this to the core application?

+1 that would be a great feature to have, and even better if it's built from HS primitives :D

Cheers,
Chris

[asmagill]

With the additions made to hs.httpserver in the latest release, everything else has basically been lua code or using things already in Hammerspoon.  Long term, to offer good CGI support with hs.task (right now it does a lot of background shuffling with temporary files), I'll probably need some additions to hs.httpserver, but that's not necessary for the lua template stuff, so it won't affect using it for a Hammerspoon documentation server.

And... the CGI stuff does work as is (tested against some Perl stuff using CGI.pm), so... I may not even bother with that side of things, since the Lua template stuff has gone so smoothly... The only real lack would be proper Markdown support, but everything I've seen so far (admittedly, I haven't looked that hard yet) is in Ruby, not Lua, and I really don't want to write one myself!

[srjpt...@gmail.com]

An Issue is raised on github for this!

                  Make documentations portable       

[asmagill]

The next release of Hammerspoon will have a built in web server which can serve the documentation on `http://localhost:12345` (by default -- this can be changed) or retrieved in a built-in `webview` by typing `hs.hsdocs()` into the Hammerspoon console.  If you're comfortable building the Hammerspoon application yourself locally, the current master repository at https://github.com/Hammerspoon/hammerspoon has this already addition.

The documentation is actually built from the same template that is used for the Dash docset, and the ultimate goal is to be able to build the docset entirely within Hammerspoon without need for external tools, but currently it doesn't support streaming the resulting HTML to a file.  I'm not sure about output to a PDF file, but my current work on another module suggests that this might be easier to add then I once feared.