def run(self, package=None, initial_text=None, prompt=False):
package = package or current_help_package()
if package is None or prompt:
return help_package_prompt(help_index_list(),
on_select=lambda pkg:
self.run(pkg, initial_text))
pkg_info = help_index_list().get(package, None)
if pkg_info is None:
return log("Cannot display topic index; unknown package '%s",
package, status=True)
topics = [pkg_info.help_topics.get(topic)
for topic in sorted(pkg_info.help_topics.keys())]
items = [[t["caption"], t["topic"]]
for t in topics]
if not items:
return log("No help topics defined for package '%s'",
package, status=True)
sublime.active_window().show_quick_panel(
items,
on_select=lambda index: self.select(pkg_info, items, index))
if initial_text:
sublime.active_window().run_command("insert", {"characters": initial_text})
def run(self, bookmark_idx):
all_bookmarks = hh_setting("bookmarks")
try:
bookmark = all_bookmarks[bookmark_idx]
except IndexError:
return log("Bookmark index was out of range", status=True)
pkg = bookmark.get("package")
topic = bookmark.get("topic")
caret = bookmark.get("caret")
viewport = bookmark.get("viewport")
if pkg is None or topic is None:
return log("Bookmark at index specified is not valid", status=True)
if show_help_topic(pkg, topic, history=True) == "file":
help_view = find_help_view()
if caret is not None:
help_view.sel().clear()
help_view.sel().add(sublime.Region(caret[0], caret[1]))
if viewport is not None:
help_view.set_viewport_position(viewport, True)
else:
help_view.show_at_center(help_view.sel()[0])
def run(self):
# The command can trigger from a build system, so don't execute if the
# build is triggered from the help view; is_enabled() is not invoked
# for build targets.
target = find_lint_target(self.window.active_view())
if target is None:
return
linters = get_linters(target)
spp = sublime.packages_path()
doc_root = target.pkg_info.doc_root
for file in target.files:
view = get_lint_file(os.path.join(spp, doc_root, file))
if view is not None:
for linter in linters:
linter.lint(view, file)
else:
log("Unable to lint '%s' in '%s'", file,
target.pkg_info.package)
issues = list()
for linter in linters:
issues += linter.results()
format_lint(target, issues, self.window)
def run(self, package=None, file=None, prompt=False):
package = package or current_help_package(window=self.window)
if package is None or prompt:
return help_package_prompt(help_index_list(),
on_select=lambda p: self.run(p, file))
pkg_info = help_index_list().get(package, None)
if pkg_info is None:
return log("Cannot edit help file; package '%s' unknown", package,
dialog=True)
files = pkg_info.help_files
items = [[key, files[key]] for key in files]
if not items:
return log("The help index for '%s' lists no help files", package,
dialog=True)
if file is not None:
return open_local_help(pkg_info, file, window=self.window)
def pick(index):
if index >= 0:
open_local_help(pkg_info, items[index][0], window=self.window)
self.window.show_quick_panel(
items=items,
on_select=lambda index: pick(index))
def reload(self, help_view, help_file):
viewport = help_view.viewport_position()
caret = help_view.sel()[0].b
if reload_help_file(help_index_list(), help_view):
help_view.sel().clear()
help_view.sel().add(sublime.Region(caret))
help_view.set_viewport_position(viewport, False)
log("Reloaded help file '%s'", help_file, status=True)
def run(self, edit, event=None):
if event is not None:
point = self.view.window_to_text((event["x"], event["y"]))
bmark_type = "file"
if self.view.match_selector(point, "meta.link"):
bmark_type = "topic"
self.view.sel().clear()
self.view.sel().add(sublime.Region(point))
sublime.run_command("hyperhelp_prompt_create_bookmark", {
"bmark_type": bmark_type})
else:
log("Cannot create a context sensitive bookmark without the mouse",
status=True)
def run(self):
# Until the log code in the bootstrap and the log code in the core are
# synchronized, manually do a dedent. I don't want to break anything
# too close to the initial package announcement.
msg = textwrap.dedent("""
About HyperHelp
HyperHelp Version: {local}
hyperhelpcore Version: {sys}
HyperHelp is a text based, hyper linked help system for
Sublime Text 3 that allows packages to display their
help directly within Sublime Text.
""").format(local=local_version, sys=sys_version).strip()
log(msg, dialog=True)
def _bookmark_at_index(bookmark_idx, displayError=False):
"""
Return the bookmark dictionary for the user bookmark at the given index, if
any. None is returned if the index is invalid. The optional argument can be
used to signal an error in the status line if the bookmark index is
invalid.
"""
all_bookmarks = _get_bookmarks()
try:
return all_bookmarks[bookmark_idx]
except IndexError:
if displayError:
log("Bookmark index was out of range", status=True)
return None
def create_file(self, package, file):
if not file:
return log("No help file given; skipping creation", status=True)
pkg_info = help_index_list().get(package)
local_path = local_help_filename(pkg_info, file)
help_file = os.path.split(local_path)
os.makedirs(help_file[0], exist_ok=True)
view = self.window.new_file()
view.settings().set("_hh_auth", True)
view.settings().set("default_dir", help_file[0])
view.set_name(help_file[1])
apply_authoring_settings(view)
template = format_template(
"""
%%hyperhelp title="${1:Title}" date="${2:%s}"
$0
""",
datetime.date.today().strftime("%Y-%m-%d"))
view.run_command("insert_snippet", {"contents": template})
def run(self, edit, quiet=False):
now = datetime.date.today().strftime("%Y-%m-%d")
h_line = self.view.line(0)
header = self.view.substr(h_line)
msg = "Help file date header is already current"
match = header_date_re.match(header)
if match and match.group(2) != now:
header = match.expand(r'\g<1>%s\g<3>' % now)
self.view.replace(edit, h_line, header)
msg = "Help file date header updated to the most recent date"
if not quiet:
log(msg, status=True)
def run(self, package=None, topic="index.txt"):
package = package or current_help_package()
topic = topic or "index.txt"
if package is None:
return log("Cannot display topic '%s'; cannot determine package",
topic, status=True)
show_help_topic(package, topic, history=True)
def __setting_changed(self):
new_list = set(self.settings.get("ignored_packages", []))
if new_list == self.cached_ignored:
return
removed = self.cached_ignored - new_list
added = new_list - self.cached_ignored
self.cached_ignored = new_list
if added:
log("unloading all help indexes loaded from: %s", list(added))
sublime.set_timeout(
lambda: unload_help_indexes_from_packges(list(added)), 2000)
if removed:
log("scanning for help indexes in: %s", list(removed))
sublime.set_timeout(
lambda: load_indexes_from_packages(list(removed)), 2000)
def run(self, package=None, prompt=False):
package = package or current_help_package(window=self.window)
if package is None or prompt:
return help_package_prompt(help_index_list(),
on_select=lambda pkg: self.run(pkg))
pkg_info = help_index_list().get(package, None)
if pkg_info is None:
return log("Cannot edit help file; package '%s' unknown", package,
dialog=True)
open_help_index(pkg_info)
def run(self, package=None, prompt=False):
package = package or current_help_package()
if package is None or prompt:
return help_package_prompt(help_index_list(),
on_select=lambda pkg: self.run(pkg))
pkg_info = help_index_list().get(package, None)
if pkg_info is None:
return log("Cannot display table of contents; unknown package '%s",
package, status=True)
self.show_toc(pkg_info, pkg_info.help_toc, [])
def run(self, edit):
# Running directly on the help view
settings = self.view.settings()
if settings.has("_hh_pkg") and settings.has("_hh_file"):
return self.reload(self.view, current_help_file())
# File must have a name and be in the packages folder.
name = self.view.file_name()
if name is None or not name.startswith(sublime.packages_path()):
return log("Unable to reload help; help file is not in a package",
status=True)
name = os.path.relpath(name, sublime.packages_path())
pkg = name.split(os.sep)[0]
file = os.path.split(name)[1]
if pkg == current_help_package() and file == current_help_file():
return self.reload(find_help_view(), file)
log("Unable to reload help; this is not the current help file",
status=True)
def show_toc(self, pkg_info, items, stack):
captions = [[item["caption"], item["topic"] +
(" ({} topics)".format(len(item["children"])) if "children" in item else "")]
for item in items]
if not captions and not stack:
return log("No help topics defined for package '%s'",
pkg_info.package, status=True)
if stack:
captions.insert(0, ["..", "Go back"])
sublime.active_window().show_quick_panel(
captions,
on_select=lambda index: self.select(pkg_info, items, stack, index))
def run(self, package=None, file=None, prompt=False):
package = package or current_help_package(window=self.window)
if package is None or prompt:
return help_package_prompt(help_index_list(),
on_select=lambda p: self.run(p, file))
if help_index_list().get(package, None) is None:
return log("Cannot add help file; package '%s' unknown",
package,
dialog=True)
if file is not None:
return self.create_file(package, file)
self.window.show_input_panel(
"New Help File (%s)" % package, "",
lambda file: self.create_file(package, file), None, None)
def open_help_index(pkg_info, window=None):
"""
Attempt to open the provided help index file localy for editing.
"""
window = window if window is not None else sublime.active_window()
# The index file is stored as a resource file spec, so strip the prefix
local_path = local_help_index(pkg_info)
if not os.path.exists(local_path):
return log(format_template(
"""
Specified help index does not exist; cannot open.
Note: HyperHelpAuthor can not currently open help
indexes from packed packages for editing.
"""), dialog=True)
window.open_file(local_path)
def open_local_help(pkg_info, help_file, window=None):
"""
Attempt to open the provided help file locally for editing.
"""
window = window if window is not None else sublime.active_window()
local_path = local_help_filename(pkg_info, help_file)
if not os.path.exists(local_path):
return log(format_template(
"""
Specified help file does not exist; cannot open.
Note: HyperHelpAuthor can not currently open help
files from packed packages for editing.
"""), dialog=True)
view = window.open_file(local_path)
view.settings().set("_hh_auth", True)
if not view.is_loading():
apply_authoring_settings(view)
def run(self, edit):
filename = self.filename()
if filename is None:
return log("Cannot reload help index; not in package", status=True)
# Make the filename be relative to the Packages folder.
filename = os.path.relpath(filename, sublime.packages_path())
filename = os.path.join("Packages/", filename)
# Flip the help index structure so we can look up the package based on
# the index file instead of the other way around.
indexes = {
value.index_file: key
for key, value in help_index_list().items()
}
# If this index is known, reload it's package; otherwise rescan all
# packages in order to bring this one in.
package = None if filename not in indexes else indexes[filename]
help_index_list(reload=True, package=package)
def error_dialog(message, *args):
"""
Simple local helper for displaying an error dialog using the log function.
"""
log(format_template(message, *args), dialog=True)
def create_index(self, package, doc_root):
root_path = self.make_document_root(package, doc_root)
if root_path is not None:
index_path = os.path.join(root_path, "hyperhelp.json")
help_path = os.path.join(root_path, "index.txt")
if os.path.exists(index_path):
return error_dialog(
"""
Help index file already exists in package:
'%s'
This may indicate that the index is broken and
cannot be loaded.
""", package)
if os.path.exists(help_path):
return error_dialog(
"""
Root help file already exists in package:
'%s'
This may indicate that an existing help index
for this package is broken and cannot be
loaded.
""", package)
try:
os.makedirs(root_path, exist_ok=True)
make_help_index(package, doc_root, index_path)
make_root_help(package, help_path)
res = posixpath.join("Packages", package, doc_root, "hyperhelp.json")
new_pkg_info = load_help_index(res)
if new_pkg_info is None:
raise IOError("Unable to load new help index")
help_index_list()[package] = new_pkg_info
msg = format_template(
"""
Initial help files created for package:
'%s'
-> %s
-> %s
""",
package,
posixpath.join(doc_root, "hyperhelp.json"),
posixpath.join(doc_root, "index.txt"))
# Prompt the user to see if they want to open the files just
# created or not.
if sublime.ok_cancel_dialog(msg, "Open created files"):
self.window.run_command("hyperhelp_author_edit_index",
{"package": package})
self.window.run_command("hyperhelp_author_edit_help",
{"package": package,
"file": "index.txt"})
# This relies on load_resource() being able to load a
# resource that find_resources() can't find yet; might
# need to make help loading open local files as for
# indexes.
sublime.run_command("hyperhelp_topic",
{"package": package,
"topic": "index.txt"})
except Exception as err:
log("Error: %s", str(err))
return error_dialog(
"""
Error adding help to package:
'%s'
Unable to create the document root, index file
or root help file.
""", package)
