Merge pull request #2281 from myk002/myk_helpdb_wrap

[helpdb] dynamically wrap long help text, preserving block indents
develop
Myk 2022-09-11 14:40:43 -07:00 committed by GitHub
commit 09372680a2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 62 additions and 7 deletions

@ -347,6 +347,10 @@ latex_toplevel_sectioning = 'part'
from sphinx.writers import text
text.MAXWIDTH = 52
# this value is arbitrary. it just needs to be bigger than the number of
# characters in the longest paragraph in the DFHack docs
text.MAXWIDTH = 1000000000
# this is the order that section headers will use the characters for underlines
# they are in the order of (subjective) text-mode readability
text_sectionchars = '=-~`+"*'

@ -3114,9 +3114,11 @@ Each entry has several properties associated with it:
Returns the short (~54 character) description for the given entry.
* ``helpdb.get_entry_long_help(entry)``
* ``helpdb.get_entry_long_help(entry[, width])``
Returns the full help text for the given entry.
Returns the full help text for the given entry. If ``width`` is specified, the
text will be wrapped at that width, preserving block indents. The wrap width
defaults to 80.
* ``helpdb.get_entry_tags(entry)``

@ -432,6 +432,37 @@ local function ensure_db()
index_tags()
end
local function parse_blocks(text)
local blocks = {}
for line in text:gmatch('[^\n]*') do
local _,indent = line:find('^ *')
table.insert(blocks, {line=line:trim(), indent=indent})
end
return blocks
end
local function format_block(line, indent, width)
local wrapped = line:wrap(width - indent)
if indent == 0 then return wrapped end
local padding = (' '):rep(indent)
local indented_lines = {}
for line in wrapped:gmatch('[^\n]*') do
table.insert(indented_lines, padding .. line)
end
return table.concat(indented_lines, '\n')
end
-- wraps the unwrapped source help at the specified width, preserving block
-- indents
local function rewrap(text, width)
local formatted_blocks = {}
for _,block in ipairs(parse_blocks(text)) do
table.insert(formatted_blocks,
format_block(block.line, block.indent, width))
end
return table.concat(formatted_blocks, '\n')
end
---------------------------------------------------------------------------
-- get API
---------------------------------------------------------------------------
@ -482,9 +513,10 @@ function get_entry_short_help(entry)
return get_db_property(entry, 'short_help')
end
-- returns the full help documentation associated with the entry
function get_entry_long_help(entry)
return get_db_property(entry, 'long_help')
-- returns the full help documentation associated with the entry, optionally
-- wrapped to the specified width (80 if not specified).
function get_entry_long_help(entry, width)
return rewrap(get_db_property(entry, 'long_help'), width or 80)
end
-- returns the set of tags associated with the entry

@ -398,8 +398,25 @@ function test.get_entry_short_help()
end
function test.get_entry_long_help()
local expected = [[
basic
*****
**Tags:** map
**Command:**
"basic"
Documented
basic.
Documented
full help.
]]
expect.eq(expected, h.get_entry_long_help('basic', 13))
-- long help for plugins/commands that have doc files should match the
-- contents of those files exactly
-- contents of those files exactly (test data is already wrapped)
expect.eq(files['hack/docs/docs/tools/hascommands.txt'],
h.get_entry_long_help('hascommands'))
expect.eq(files['hack/docs/docs/tools/hascommands.txt'],