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
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

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 (29 lines)

Diff 15015

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): def helpcategory(cmd):
# For now, the category header is at the same level as the headers for # For 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. # the commands in the category; this is fixed in the next commit.
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
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