This is an archive of the discontinued Mercurial Phabricator instance.

Differential D6329

gendoc: nest command headers under category headers
ClosedPublic

Authored by Sietse on Apr 28 2019, 5:17 PM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHGa42cc325b682: gendoc: nest command headers under category headers
Summary

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

Sietse created this revision.Apr 28 2019, 5:17 PM
Sietse added a comment.EditedApr 29 2019, 9:51 AM

Changing this script affects hg.1 and hg.1.html. I have uploaded the original output, and the output after this patch stack; links below.

hg.1:

  • (original)
    1-original-hg.1450 KBDownload
  • (by category, with nested headers)
    final-hg.1451 KBDownload

hg.1.html:

  • (original)
    1-original-hg.1.html714 KBDownload
    (original)
  • (by category, with nested headers)
    final-hg.1.html719 KBDownload
Sietse updated this revision to Diff 14991.May 3 2019, 9:36 AM
Sietse updated this revision to Diff 15000.May 4 2019, 10:36 AM
Sietse added inline comments.May 4 2019, 12:06 PM
doc/gendoc.py
201

Could somebody confirm the new hg.1 man page and hg.1.html output look okay? I've linked them (and the originals) in the comment at the top of this page above. They are extremely user-facing, so I'm anxious to have a second pair of eyes go over them.

martinvonz added a subscriber: martinvonz.May 5 2019, 1:06 AM

Queuing this, thanks.

doc/gendoc.py
201

I looked at the html and it looked fine to me

Closed by commit rHGa42cc325b682: gendoc: nest command headers under category headers (authored by Sietse). · Explain WhyMay 5 2019, 1:12 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mdoc/gendoc.py (33 lines)

Diff 14962

doc/gendoc.py

if optstr.endswith(b"[+]>"): if optstr.endswith(b"[+]>"):
multioccur = True multioccur = True
if multioccur: if multioccur:
ui.write(_(b"\n[+] marked option can be specified multiple times\n")) ui.write(_(b"\n[+] marked option can be specified multiple times\n"))
ui.write(b"\n") ui.write(b"\n")
# print cmds # print cmds
ui.write(minirst.section(_(b"Commands"))) ui.write(minirst.section(_(b"Commands")))
commandprinter(ui, table, minirst.subsection) commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
# print help topics # print help topics
# The config help topic is included in the hgrc.5 man page. # The config help topic is included in the hgrc.5 man page.
helpprinter(ui, helptable, minirst.section, exclude=[b'config']) helpprinter(ui, helptable, minirst.section, exclude=[b'config'])
ui.write(minirst.section(_(b"Extensions"))) ui.write(minirst.section(_(b"Extensions")))
ui.write(_(b"This section contains help for extensions that are " ui.write(_(b"This section contains help for extensions that are "
b"distributed together with Mercurial. Help for other " b"distributed together with Mercurial. Help for other "
b"extensions is available in the help system.")) b"extensions is available in the help system."))
ui.write((b"\n\n" ui.write((b"\n\n"
b".. contents::\n" b".. contents::\n"
b" :class: htmlonly\n" b" :class: htmlonly\n"
b" :local:\n" b" :local:\n"
b" :depth: 1\n\n")) b" :depth: 1\n\n"))
for extensionname in sorted(allextensionnames()): for extensionname in sorted(allextensionnames()):
mod = extensions.load(ui, extensionname, None) mod = extensions.load(ui, extensionname, None)
ui.write(minirst.subsection(extensionname)) ui.write(minirst.subsection(extensionname))
ui.write(b"%s\n\n" % gettext(pycompat.getdoc(mod))) ui.write(b"%s\n\n" % gettext(pycompat.getdoc(mod)))
cmdtable = getattr(mod, 'cmdtable', None) cmdtable = getattr(mod, 'cmdtable', None)
if cmdtable: if cmdtable:
ui.write(minirst.subsubsection(_(b'Commands'))) ui.write(minirst.subsubsection(_(b'Commands')))
commandprinter(ui, cmdtable, minirst.subsubsubsection) commandprinter(ui, cmdtable, minirst.subsubsubsection,
minirst.subsubsubsubsection)
def showtopic(ui, topic): def showtopic(ui, topic):
extrahelptable = [ extrahelptable = [
([b"common"], b'', loaddoc(b'common'), help.TOPIC_CATEGORY_MISC), ([b"common"], b'', loaddoc(b'common'), help.TOPIC_CATEGORY_MISC),
([b"hg.1"], b'', loaddoc(b'hg.1'), help.TOPIC_CATEGORY_CONFIG), ([b"hg.1"], b'', loaddoc(b'hg.1'), help.TOPIC_CATEGORY_CONFIG),
([b"hg-ssh.8"], b'', loaddoc(b'hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG), ([b"hg-ssh.8"], b'', loaddoc(b'hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG),
([b"hgignore.5"], b'', loaddoc(b'hgignore.5'), ([b"hgignore.5"], b'', loaddoc(b'hgignore.5'),
help.TOPIC_CATEGORY_CONFIG), help.TOPIC_CATEGORY_CONFIG),
ui.write(b"\n") ui.write(b"\n")
if sectionfunc: if sectionfunc:
ui.write(sectionfunc(sec)) ui.write(sectionfunc(sec))
if callable(doc): if callable(doc):
doc = doc(ui) doc = doc(ui)
ui.write(doc) ui.write(doc)
ui.write(b"\n") ui.write(b"\n")
def commandprinter(ui, cmdtable, sectionfunc): def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
"""Render restructuredtext describing a list of commands and their
documentations, grouped by command category.
Args:
ui: UI object to write the output to
cmdtable: a dict that maps a string of the command name plus its aliases
(separated with pipes) to a 3-tuple of (the command's function, a list
of its option descriptions, and a string summarizing available
options). Example, with aliases added for demonstration purposes:
'phase|alias1|alias2': (
<function phase at 0x7f0816b05e60>,
[ ('p', 'public', False, 'set changeset phase to public'),
...,
('r', 'rev', [], 'target revision', 'REV')],
'[-p|-d|-s] [-f] [-r] [REV...]'
)
sectionfunc: minirst function to format command category headers
subsectionfunc: minirst function to format command headers
"""
SietseAuthorUnsubmitted
Not Done

Could somebody confirm the new hg.1 man page and hg.1.html output look okay? I've linked them (and the originals) in the comment at the top of this page above. They are extremely user-facing, so I'm anxious to have a second pair of eyes go over them.

Sietse: Could somebody confirm the new `hg.1` man page and `hg.1.html` output look okay? I've linked…
martinvonzUnsubmitted
Not Done

I looked at the html and it looked fine to me

martinvonz: I looked at the html and it looked fine to me
h = {} h = {}
for c, attr in cmdtable.items(): for c, attr in cmdtable.items():
f = c.split(b"|")[0] f = c.split(b"|")[0]
f = f.lstrip(b"^") f = f.lstrip(b"^")
h[f] = c h[f] = c
cmds = h.keys() cmds = h.keys()
def helpcategory(cmd, h=h, cmdtable=cmdtable): def helpcategory(cmd, h=h, cmdtable=cmdtable):
for category in help.CATEGORY_ORDER: for category in help.CATEGORY_ORDER:
# Make a list of the commands in this category. # Make a list of the commands in this category.
# Rescanning the list of all commands for each category is quadratic; # Rescanning the list of all commands for each category is quadratic;
# this is justified because N is low, and repeating the lookup keeps # this is justified because N is low, and repeating the lookup keeps
# our data structure simpler. # our data structure simpler.
categorycmds = sorted([ categorycmds = sorted([
cmd for cmd in cmds cmd for cmd in cmds
if helpcategory(cmd) == category]) if helpcategory(cmd) == category])
# Print a section header for the category. Skip empty categories. For # Print a section header for the category. Skip empty categories.
# now, the category header is at the same level as the headers for the
# commands in the category; this is fixed in the next commit.
if categorycmds: if categorycmds:
ui.write(sectionfunc(help.CATEGORY_NAMES[category])) ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
# Print each command in the category # Print each command in the category
for f in sorted(categorycmds): for f in sorted(categorycmds):
if f.startswith(b"debug"): if f.startswith(b"debug"):
continue continue
processedcmds.append(f) # log command processedcmds.append(f) # log command
d = get_cmd(h[f], cmdtable) d = get_cmd(h[f], cmdtable)
ui.write(sectionfunc(d[b'cmd'])) ui.write(subsectionfunc(d[b'cmd']))
# short description # short description
ui.write(d[b'desc'][0]) ui.write(d[b'desc'][0])
# synopsis # synopsis
ui.write(b"::\n\n") ui.write(b"::\n\n")
synopsislines = d[b'synopsis'].splitlines() synopsislines = d[b'synopsis'].splitlines()
for line in synopsislines: for line in synopsislines:
# some commands (such as rebase) have a multi-line # some commands (such as rebase) have a multi-line
# synopsis # synopsis