docs » hs.doc.hsdocs

Manage the internal documentation web server.

This module provides functions for managing the Hammerspoon built-in documentation web server. Currently, this is the same documentation available in the Dash docset for Hammerspoon, but does not require third party software for viewing.

Future enhancements to this module under consideration include:

The intent of this sub-module is to provide as close a rendering of the same documentation available at the Hammerspoon Github site and Dash documentation as possible in a manner suitable for run-time modification so module developers can test out documentation additions without requiring a complete recompilation of the Hammerspoon source. As always, the most current and official documentation can be found at http://www.hammerspoon.org and in the official Hammerspoon Dash docset.

API Overview

API Documentation

Functions

browserDarkMode
Signature hs.doc.hsdocs.browserDarkMode([value]) -> currentValue
Type Function
Description

Get or set whether or not the Hammerspoon browser renders output in Dark mode.

Paramters:

  • value - an optional boolean, number, or nil specifying whether or not the documentation browser renders in Dark mode.
    • if value is true, then the HTML output will always be inverted
    • if value is false, then the HTML output will never be inverted
    • if value is nil, then the output will be inverted only when the OS X theme is set to Dark mode
    • if the value is a number between 0 and 100, the number specifies the inversion ratio, where 0 means no inversion, 100 means full inversion, and 50 is completely unreadable because the foreground and background are equally adjusted.

Returns:

  • the current, possibly new, value

Notes:

  • Inversion is applied through the use of CSS filtering, so while numeric values other than 0 (false) and 100 (true) are allowed, the result is generally not what is desired.

  • This value is stored in the Hammerspoon application defaults with the label "_documentationServer.invertDocs".

browserFrame
Signature hs.doc.hsdocs.browserFrame([frameTable]) -> currentValue
Type Function
Description

Get or set the currently saved initial frame location for the documentation browser.

Parameters:

  • frameTable - a frame table containing x, y, h, and w values specifying the browser's initial position when Hammerspoon starts.

Returns:

  • the current, possibly new, value

Notes:

  • If hs.doc.hsdocs.trackBrowserFrame is false or nil (the default), then you can use this function to specify the initial position of the documentation browser.
  • If hs.doc.hsdocs.trackBrowserFrame is true, then this any value set with this function will be overwritten whenever the browser window is moved or resized.

  • This value is stored in the Hammerspoon application defaults with the label "_documentationServer.browserFrame".

forceExternalBrowser
Signature hs.doc.hsdocs.forceExternalBrowser([value]) -> currentValue
Type Function
Description

Get or set whether or not hs.doc.hsdocs.help uses an external browser.

Paramters:

  • value - an optional boolean or string, default false, specifying whether or not documentation requests will be displayed in an external browser or the internal one handled by hs.webview.

Returns:

  • the current, possibly new, value

Notes:

  • If this value is set to true, help requests invoked by hs.doc.hsdocs.help will be invoked by your system's default handler for the http scheme.
  • If this value is set to a string, the string specifies the bundle ID of an application which will be used to handle the url request for the documentation. The string should match one of the items returned by hs.urlevent.getAllHandlersForScheme("http").

  • This behavior is triggered automatically, regardless of this setting, if you are running with a version of OS X prior to 10.10, since hs.webview requires OS X 10.10 or later.

  • This value is stored in the Hammerspoon application defaults with the label "_documentationServer.forceExternalBrowser".

help
Signature hs.doc.hsdocs.help([identifier]) -> nil
Type Function
Description

Display the documentation for the specified Hammerspoon function, or the Table of Contents for the Hammerspoon documentation in a built-in mini browser.

Parameters:

  • an optional string specifying a Hammerspoon module, function, or method to display documentation for. If you leave out this parameter, the table of contents for the Hammerspoon built-in documentation is displayed instead.

Returns:

  • None
port
Signature hs.doc.hsdocs.port([value]) -> currentValue
Type Function
Description

Get or set the Hammerspoon documentation server HTTP port.

Paramters:

  • value - an optional number specifying the port for the Hammerspoon documentation web server

Returns:

  • the current, possibly new, value

Notes:

  • The default port number is 12345.

  • This value is stored in the Hammerspoon application defaults with the label "_documentationServer.serverPort".

start
Signature hs.doc.hsdocs.start() -> `hs.doc.hsdocs`
Type Function
Description

Start the Hammerspoon internal documentation web server.

Parameters:

  • None

Returns:

  • the table representing the hs.doc.hsdocs module

Notes:

  • This function is automatically called, if necessary, when hs.doc.hsdocs.help is invoked.
  • The documentation web server can be viewed from a web browser by visiting "http://localhost:port" where port is the port the server is running on, 12345 by default -- see hs.doc.hsdocs.port.
stop
Signature hs.doc.hsdocs.stop() -> `hs.doc.hsdocs`
Type Function
Description

Stop the Hammerspoon internal documentation web server.

Parameters:

  • None

Returns:

  • the table representing the hs.doc.hsdocs module
trackBrowserFrame
Signature hs.doc.hsdocs.trackBrowserFrame([value]) -> currentValue
Type Function
Description

Get or set whether or not changes in the documentation browsers location and size persist through launches of Hammerspoon.

Parameters:

  • value - an optional boolean specifying whether or not the browsers location should be saved across launches of Hammerspoon.

Returns:

  • the current, possibly new, value

Notes:

  • This value is stored in the Hammerspoon application defaults with the label "_documentationServer.trackBrowserFrameChanges".