Merge pull request #2702 from myk002/myk_no_helpdb_autorefresh

move helpdb from autorefresh to explicit refresh
develop
Myk 2023-01-23 11:20:14 -08:00 committed by GitHub
commit 7eb3de8e1a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 25 additions and 24 deletions

@ -40,6 +40,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
## Misc Improvements
- A new cross-compile build script was added for building the Windows files from a Linux Docker builder (see the Compile instructions in the docs)
- `hotkeys`: clicking on the DFHack logo no longer closes the popup menu
- `gui/launcher`: sped up initialization time for faster load of the UI
- `orders`: orders plugin functionality is now offered via an overlay widget when the manager orders screen is open
## Documentation
@ -47,6 +48,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
## API
## Lua
- `helpdb`: new function: ``helpdb.refresh()`` to force a refresh of the database. Call if you are a developer adding new scripts, loading new plugins, or changing help text during play
- `helpdb`: changed from auto-refreshing every 60 seconds to only refreshing on explicit call to ``helpdb.refresh()``. docs very rarely change during a play session, and the automatic database refreshes were slowing down the startup of `gui/launcher`
- ``widgets.Label``: ``label.scroll()`` now understands ``home`` and ``end`` keywords for scrolling to the top or bottom
## Removed

@ -3319,17 +3319,20 @@ function:
argument specifies the indentation step size in spaces. For
the other arguments see the original documentation link above.
.. _helpdb:
helpdb
======
Unified interface for DFHack tool help text. Help text is read from the rendered
text in ``hack/docs/docs/``. If no rendered text exists, help is read from the
script sources (for scripts) or the string passed to the ``PluginCommand``
text in ``hack/docs/docs/tools``. If no rendered text exists, help is read from
the script sources (for scripts) or the string passed to the ``PluginCommand``
initializer (for plugins). See `documentation` for details on how DFHack's help
system works.
The database is lazy-loaded when an API method is called. It rechecks its help
sources for updates if an API method has not been called in the last 60 seconds.
The database is loaded when DFHack initializes, but can be explicitly refreshed
with a call to ``helpdb.refresh()`` if docs are added/changed during a play
session.
Each entry has several properties associated with it:
@ -3345,6 +3348,10 @@ Each entry has several properties associated with it:
- Long help, the entire contents of the associated help file.
- A list of tags that define the groups that the entry belongs to.
* ``helpdb.refresh()``
Scan for changes in available commands and their documentation.
* ``helpdb.is_entry(str)``, ``helpdb.is_entry(list)``
Returns whether the given string (or list of strings) is an entry (are all

@ -2114,6 +2114,7 @@ void Core::onStateChange(color_ostream &out, state_change_event event)
{
auto L = Lua::Core::State;
Lua::StackUnwinder top(L);
Lua::CallLuaModuleFunction(con, L, "helpdb", "refresh");
Lua::CallLuaModuleFunction(con, L, "script-manager", "reload");
}
break;

@ -1,23 +1,9 @@
-- The help text database and query interface.
--
-- Help text is read from the rendered text in hack/docs/docs/. If no rendered
-- text exists, it is read from the script sources (for scripts) or the string
-- passed to the PluginCommand initializer (for plugins).
--
-- There should be one help file for each plugin that contains a summary for the
-- plugin itself and help for all the commands that plugin provides (if any).
-- Each script should also have one documentation file.
--
-- The database is lazy-loaded when an API method is called. It rechecks its
-- help sources for updates if an API method has not been called in the last
-- 60 seconds.
local _ENV = mkmodule('helpdb')
local argparse = require('argparse')
local MAX_STALE_MS = 60000
-- paths
local RENDERED_PATH = 'hack/docs/docs/tools/'
local TAG_DEFINITIONS = 'hack/docs/docs/Tags.txt'
@ -415,13 +401,12 @@ local function index_tags()
end
end
-- ensures the db is up to date by scanning all help sources. does not do
-- anything if it has already been run within the last MAX_STALE_MS milliseconds
local last_refresh_ms = 0
local needs_refresh = true
-- ensures the db is loaded
local function ensure_db()
local now_ms = dfhack.getTickCount()
if now_ms - last_refresh_ms <= MAX_STALE_MS then return end
last_refresh_ms = now_ms
if not needs_refresh then return end
needs_refresh = false
local old_db = textdb
textdb, entrydb, tag_index = {}, {}, {}
@ -433,6 +418,11 @@ local function ensure_db()
index_tags()
end
function refresh()
needs_refresh = true
ensure_db()
end
local function parse_blocks(text)
local blocks = {}
for line in text:gmatch('[^\n]*') do