Skip to content

doc: properly handle preformatted blocks #8242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ SORT=LC_ALL=C sort


ifeq ($V,1)
VERBOSE = $(ECHO) '$(2)'; $(2)
VERBOSE = $(ECHO) '$(subst ','\'',$(2))'; $(2)
else
VERBOSE = $(ECHO) $(1); $(2)
endif
Expand Down
11 changes: 7 additions & 4 deletions contrib/msggen/msggen/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -28990,9 +28990,9 @@
"description": [
"Determines what action is taken:",
" - *subcommand* **start** takes a *path* to an executable as argument and starts it as plugin. *path* may be an absolute path or a path relative to the plugins directory (default *~/.lightning/plugins*). If the plugin is already running and the executable (checksum) has changed, the plugin is killed and restarted except if its an important (or builtin) plugin. If the plugin doesn't complete the 'getmanifest' and 'init' handshakes within 60 seconds, the command will timeout and kill the plugin. Additional *options* may be passed to the plugin, but requires all parameters to be passed as keyword=value pairs using the `-k|--keyword` option which is recommended. For example the following command starts the plugin helloworld.py (present in the plugin directory) with the option greeting set to 'A crazy':",
" ```shell.",
" lightning-cli -k plugin subcommand=start plugin=helloworld.py greeting='A crazy'.",
" ```.",
" ```shell",
" lightning-cli -k plugin subcommand=start plugin=helloworld.py greeting='A crazy'",
" ```",
" - *subcommand* **stop** takes a plugin executable *path* or *name* as argument and stops the plugin. If the plugin subscribed to 'shutdown', it may take up to 30 seconds before this command returns. If the plugin is important and dynamic, this will shutdown `lightningd`.",
" - *subcommand* **startdir** starts all executables it can find in *directory* (excl. subdirectories) as plugins. Checksum and timeout behavior as in **start** applies.",
" - *subcommand* **rescan** starts all plugins in the default plugins directory (default *~/.lightning/plugins*) that are not already running. Checksum and timeout behavior as in **start** applies.",
Expand Down Expand Up @@ -33060,7 +33060,10 @@
"relative_amount": {
"type": "integer",
"description": [
"A positive or negative amount of satoshis to add or subtract from the channel. Note you may need to add a double dash (--) after splice_init if using a negative *relative_amount* so it is not interpretted as a command modifier. For example: ```shell lightning-cli splice_init -- $CHANNEL_ID -100000 ```."
"A positive or negative amount of satoshis to add or subtract from the channel. Note you may need to add a double dash (--) after splice_init if using a negative *relative_amount* so it is not interpretted as a command modifier. For example:",
"```shell",
"lightning-cli splice_init -- $CHANNEL_ID -100000",
"```"
]
},
"initialpsbt": {
Expand Down
6 changes: 3 additions & 3 deletions doc/schemas/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@
"description": [
"Determines what action is taken:",
" - *subcommand* **start** takes a *path* to an executable as argument and starts it as plugin. *path* may be an absolute path or a path relative to the plugins directory (default *~/.lightning/plugins*). If the plugin is already running and the executable (checksum) has changed, the plugin is killed and restarted except if its an important (or builtin) plugin. If the plugin doesn't complete the 'getmanifest' and 'init' handshakes within 60 seconds, the command will timeout and kill the plugin. Additional *options* may be passed to the plugin, but requires all parameters to be passed as keyword=value pairs using the `-k|--keyword` option which is recommended. For example the following command starts the plugin helloworld.py (present in the plugin directory) with the option greeting set to 'A crazy':",
" ```shell.",
" lightning-cli -k plugin subcommand=start plugin=helloworld.py greeting='A crazy'.",
" ```.",
" ```shell",
" lightning-cli -k plugin subcommand=start plugin=helloworld.py greeting='A crazy'",
" ```",
" - *subcommand* **stop** takes a plugin executable *path* or *name* as argument and stops the plugin. If the plugin subscribed to 'shutdown', it may take up to 30 seconds before this command returns. If the plugin is important and dynamic, this will shutdown `lightningd`.",
" - *subcommand* **startdir** starts all executables it can find in *directory* (excl. subdirectories) as plugins. Checksum and timeout behavior as in **start** applies.",
" - *subcommand* **rescan** starts all plugins in the default plugins directory (default *~/.lightning/plugins*) that are not already running. Checksum and timeout behavior as in **start** applies.",
Expand Down
5 changes: 4 additions & 1 deletion doc/schemas/splice_init.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@
"relative_amount": {
"type": "integer",
"description": [
"A positive or negative amount of satoshis to add or subtract from the channel. Note you may need to add a double dash (--) after splice_init if using a negative *relative_amount* so it is not interpretted as a command modifier. For example: ```shell lightning-cli splice_init -- $CHANNEL_ID -100000 ```."
"A positive or negative amount of satoshis to add or subtract from the channel. Note you may need to add a double dash (--) after splice_init if using a negative *relative_amount* so it is not interpretted as a command modifier. For example:",
"```shell",
"lightning-cli splice_init -- $CHANNEL_ID -100000",
"```"
]
},
"initialpsbt": {
Expand Down
6 changes: 3 additions & 3 deletions tools/fromschema.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ def output_title(title, underline='-', num_leading_newlines=1, num_trailing_newl

def esc_underscores(s):
"""Backslash-escape underscores outside of backtick-enclosed spans"""
return ''.join(['\\_' if x == '_' else x for x in re.findall(r'[^`_\\]+|`(?:[^`\\]|\\.)*`|\\.|_', s)])
return ''.join(['\\_' if x == '_' else x for x in re.findall(r'(?ms:^[ \t]*```.*?^[ \t]*```)|[^`_\\\n]+|`(?:[^`\\]|\\.)*`|\\.|[_\n]', s)])


def json_value(obj):
Expand Down Expand Up @@ -165,8 +165,8 @@ def output_member(propname, properties, is_optional, indent, print_type=True, pr
output_range(properties)

if 'description' in properties:
for i in range(0, len(properties['description'])):
output('{} {}{}'.format(':' if i == 0 else '', esc_underscores(properties['description'][i]), '' if i + 1 == len(properties['description']) else '\n'))
output(': ')
outputs(properties['description'], '\n ')

if 'default' in properties:
output(' The default is {}.'.format(esc_underscores(properties['default']) if isinstance(properties['default'], str) else properties['default']))
Expand Down
10 changes: 6 additions & 4 deletions tools/md2man.sh
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,17 @@ TITLELINE="$(head -n1 "$SOURCE")"

# Replace lightning-cli with $ lightning-cli but do not replace it if it is preceded with (
# because it is used in the examples to run it in the shell, eg. $(lightning-cli listpeerchannels)
# shellcheck disable=SC2016 # These are not variables, shellcheck!
SOURCE=$(tail -n +3 "$SOURCE" | sed -E '
:a;N;$!ba;
s#EXAMPLES\n------------#\nEXAMPLES\n------------\n#g;
s#Request:#Request:\n#g;
s#Response:#Response:\n#g;
s#(\(lightning-cli)#\x1#ig;
s#lightning-cli#$ lightning-cli#g;
s#\x1#(lightning-cli#g;
s#\*\*Notification (1|2|3)\*\*:#**Notification \1**:\n#g;
' |
# Lowdown requires a blank line before every preformatted text block
sed '
/^$/{:0;N;/\n$/b0};s/^[[:blank:]]*```/\n\0/;
/\n[[:blank:]]*```/{:1;n;/^[[:blank:]]*```/!b1}
')

# Output to the target file
Expand Down
Loading