Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-08 02:34:06 -04:00
Code Issues Packages Projects Releases Wiki Activity

When generating sphinx documentation from command line usage/options, try to recognize and mark references to option in the help text

Browse Source
This commit is contained in:
Kovid Goyal 2014-06-17 18:07:20 +05:30
parent 033a8a2421
commit a837586bb9
1 changed files with 9 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
manual/custom.py
View File

@ -184,11 +184,17 @@ def render_options(cmd, groups, options_header=True, add_program=True):
y.get_opt_string())): y.get_opt_string())):
help = opt.help if opt.help else '' help = opt.help if opt.help else ''
help = help.replace('\n', ' ').replace('*', '\\*').replace('%default', str(opt.default)) help = help.replace('\n', ' ').replace('*', '\\*').replace('%default', str(opt.default))
help = mark_options(help)
opt = opt.get_opt_string() + ((', '+', '.join(opt._short_opts)) if opt._short_opts else '') opt = opt.get_opt_string() + ((', '+', '.join(opt._short_opts)) if opt._short_opts else '')
opt = '.. cmdoption:: '+opt opt = '.. cmdoption:: '+opt
lines.extend([opt, '', ' '+help, '']) lines.extend([opt, '', ' '+help, ''])
return lines return lines
def mark_options(raw):
raw = re.sub(r'(\s+)--(\s+)', r'\1``--``\2', raw)
raw = re.sub(r'(--[a-zA-Z0-9_=,-]+)', r':option:`\1`', raw)
return raw
def cli_docs(app): def cli_docs(app):
info = app.builder.info info = app.builder.info
info(bold('creating CLI documentation...')) info(bold('creating CLI documentation...'))
@ -209,8 +215,8 @@ def cli_docs(app):
documented_cmds.sort(cmp=lambda x, y: cmp(x[0], y[0])) documented_cmds.sort(cmp=lambda x, y: cmp(x[0], y[0]))
undocumented_cmds.sort() undocumented_cmds.sort()
documented = [' '*4 + cmd[0] for cmd in documented_cmds] documented = [' '*4 + c[0] for c in documented_cmds]
undocumented = [' * ' + cmd for cmd in undocumented_cmds] undocumented = [' * ' + c for c in undocumented_cmds]
raw = CLI_INDEX.format(documented='\n'.join(documented), raw = CLI_INDEX.format(documented='\n'.join(documented),
undocumented='\n'.join(undocumented)) undocumented='\n'.join(undocumented))
@ -219,7 +225,7 @@ def cli_docs(app):
update_cli_doc(os.path.join('cli', 'cli-index.rst'), raw, info) update_cli_doc(os.path.join('cli', 'cli-index.rst'), raw, info)
for cmd, parser in documented_cmds: for cmd, parser in documented_cmds:
usage = [i for i in parser.usage.replace('%prog', cmd).splitlines()] usage = [mark_options(i) for i in parser.usage.replace('%prog', cmd).splitlines()]
cmdline = usage[0] cmdline = usage[0]
usage = usage[1:] usage = usage[1:]
usage = [i.replace(cmd, ':command:`%s`'%cmd) for i in usage] usage = [i.replace(cmd, ':command:`%s`'%cmd) for i in usage]