This is an archive of the discontinued Mercurial Phabricator instance.

Differential D9135

doc: Generate separate commands/topics/extension web pages.
Needs RevisionPublic

Authored by ludovicchabant on Sep 30 2020, 5:35 PM.

Details

Reviewers
baymax
Group Reviewers
hg-reviewers

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

ludovicchabant created this revision.Sep 30 2020, 5:35 PM
ludovicchabant added a comment.EditedSep 30 2020, 5:40 PM

Hi there... this patch is a proof of concept, and probably entirely the wrong approach since I was learning Makefiles almost from scratch as I was doing it (and then by the end realized it only works with recent versions of Make). But I'd like to put the basic idea of the change up for review at least before I continue working on it.

The basic idea is that the Mercurial reference page is too damn big and unwieldy. Its size also makes it hard to search for something only for a given command. One could search through the help output in a terminal but there is tremendous value in having a well organized and friendly website. Anyway, this change makes it possible to spit out separate web pages for each command, topic, and extension, along with a classified index page that links to all of them.

Thanks

durin42 added a subscriber: durin42.Oct 14 2020, 3:41 PM

I like it. Did you intend this as an RFC, or for landing?

ludovicchabant added a comment.EditedDec 2 2020, 5:57 PM

Derp... phabricator didn't send me any email notification....

Anyway, if the implementation is roughly ok we can do a code review and queue it for next release. If not, I can redo it using a better approach? I'm not sure what "RFC" and "landing" mean in the specific context of the mercurial release workflow, so whichever one is more appropriate is fine by me! The main things I'd like to have feedback on are:

  1. The method I'm using here requires a recent Make (for instance, the one that ships by default on macOS won't work). I don't know if there's a better way to do this?
  2. This generates a bunch of intermediate and final files, which increases the make docs time. I don't know if process time is an issue here, or if it's OK because it's run only once per release?
  3. I took a bit of creative freedom for the format of the new pages. This is easy to iterate upon a bit later but it's worth taking a look at the output in case you have any opinions.

Thanks!

durin42 added a comment.Jan 1 2021, 10:06 PM

I'm fine with this as long as it still works on Python 3. Can you confirm this works under Python 3? Maybe rebase it to @ for completeness, since it's been a while.

Sorry for slow responses.

baymax requested changes to this revision.Aug 18 2021, 9:39 AM

There seems to have been no activities on this Diff for the past 3 Months.

By policy, we are automatically moving it out of the need-review state.

Please, move it back to need-review without hesitation if this diff should still be discussed.

:baymax:need-review-idle:

This revision now requires changes to proceed.Aug 18 2021, 9:39 AM

Revision Contents
Changeset List

PathPackages
M.hgignore (11 lines)
Mdoc/Makefile (104 lines)
Mdoc/gendoc.py (362 lines)
AMdoc/templates/cmdheader.txt (22 lines)
AMdoc/templates/extheader.txt (4 lines)
AMdoc/templates/topicheader.txt (4 lines)

Diff 22957

.hgignore

tests/htmlcov tests/htmlcov
build build
contrib/chg/chg contrib/chg/chg
contrib/hgsh/hgsh contrib/hgsh/hgsh
contrib/vagrant/.vagrant contrib/vagrant/.vagrant
dist dist
packages packages
doc/common.txt doc/common.txt
doc/commandlist.txt
doc/extensionlist.txt
doc/topiclist.txt
doc/*.mk
doc/*.[0-9] doc/*.[0-9]
doc/*.[0-9].txt doc/*.[0-9].txt
doc/*.[0-9].gendoc.txt doc/*.{x,ht}ml
doc/*.[0-9].{x,ht}ml doc/*.gendoc.txt
doc/hg-*.html
doc/topic-*.html
doc/ext-*.html
MANIFEST MANIFEST
MANIFEST.in MANIFEST.in
patches patches
mercurial/__modulepolicy__.py mercurial/__modulepolicy__.py
mercurial/__version__.py mercurial/__version__.py
mercurial/hgpythonlib.h mercurial/hgpythonlib.h
mercurial.egg-info mercurial.egg-info
.DS_Store .DS_Store

doc/Makefile

SOURCES=$(notdir $(wildcard ../mercurial/helptext/*.[0-9].txt)) SOURCES=$(notdir $(wildcard ../mercurial/helptext/*.[0-9].txt))
MAN=$(SOURCES:%.txt=%) MAN=$(SOURCES:%.txt=%)
HTML=$(SOURCES:%.txt=%.html) HTML=$(SOURCES:%.txt=%.html) index.html
GENDOC=gendoc.py ../mercurial/commands.py ../mercurial/help.py \ GENDOC=gendoc.py ../mercurial/commands.py ../mercurial/help.py \
../mercurial/helptext/*.txt ../hgext/*.py ../hgext/*/__init__.py ../mercurial/helptext/*.txt ../hgext/*.py ../hgext/*/__init__.py
HGCMDTPL=templates/cmdheader.txt
TOPICTPL=templates/topicheader.txt
EXTTPL=templates/extheader.txt
PREFIX=/usr/local PREFIX=/usr/local
MANDIR=$(PREFIX)/share/man MANDIR=$(PREFIX)/share/man
INSTALL=install -m 644 INSTALL=install -m 644
PYTHON?=python PYTHON?=python
RSTARGS= RSTARGS=
export HGENCODING=UTF-8 export HGENCODING=UTF-8
.PHONY: all man html install clean
# Generate a list of hg commands and extensions.
commandlist.txt: $(GENDOC)
${PYTHON} gendoc.py commandlist > $@.tmp
mv $@.tmp $@
topiclist.txt: $(GENDOC)
${PYTHON} gendoc.py topiclist > $@.tmp
mv $@.tmp $@
extensionlist.txt: $(GENDOC)
${PYTHON} gendoc.py extensionlist > $@.tmp
mv $@.tmp $@
# Generate a sub-Makefile that can build the RST/man/html doc for
# each hg command.
define RuleAllCommandsTemplate
HG_COMMANDS=$(1)
all-commands: $$(HG_COMMANDS:%=hg-%.gendoc.txt)
endef
define RuleAllTopicsTemplate
HG_TOPICS=$(1)
all-topics: $$(HG_TOPICS:%=%.gendoc.txt)
endef
define RuleAllExtensionsTemplate
HG_EXTENSIONS=$(1)
all-extensions: $$(HG_EXTENSIONS:%=%.gendoc.txt)
endef
define RuleCommandTemplate
hg-$C.gendoc.txt: $$(GENDOC) $$(HGCMDTPL)
$$(PYTHON) gendoc.py cmd-$C > $$@.tmp
mv $$@.tmp $$@
endef
define RuleTopicTemplate
topic-$T.gendoc.txt: $$(GENDOC) $$(TOPICTPL)
$$(PYTHON) gendoc.py topic-$T > $$@.tmp
mv $$@.tmp $$@
endef
define RuleExtensionTemplate
ext-$E.gendoc.txt: $$(GENDOC) $$(EXTTPL)
$$(PYTHON) gendoc.py ext-$E > $$@.tmp
mv $$@.tmp $$@
endef
# Note that this type of stuff is only supported by GNU Make 4 and above.
# Check the version you have installed if this rule fails.
CommandsTopicsExtensions.mk: commandlist.txt topiclist.txt extensionlist.txt Makefile
$(file > $@.tmp,# Generated by Makefile)
$(file >> $@.tmp,$(call RuleAllCommandsTemplate,$(file < commandlist.txt)))
$(file >> $@.tmp,$(call RuleAllTopicsTemplate,$(file < topiclist.txt)))
$(file >> $@.tmp,$(call RuleAllExtensionsTemplate,$(file < extensionlist.txt)))
$(foreach C,$(file < commandlist.txt),$(file >> $@.tmp,$(RuleCommandTemplate)))
$(foreach T,$(file < topiclist.txt),$(file >> $@.tmp,$(RuleTopicTemplate)))
$(foreach E,$(file < extensionlist.txt),$(file >> $@.tmp,$(RuleExtensionTemplate)))
mv $@.tmp $@
# Include the sub-Makefile.
# NOTE: since we define (above) a rule for this sub-Makefile, make will
# automatically try to generate it if it's not up to date, and then
# will restart itself using the newly generated file.
ifeq (,$(filter clean,$(MAKECMDGOALS)))
-include CommandsTopicsExtensions.mk
endif
# If the sub-Makefile is available, add all the hg commands/topics/extensions
# to the list of things to generate html pages for.
ifdef HG_COMMANDS
HTML+=$(HG_COMMANDS:%=hg-%.html)
endif
ifdef HG_TOPICS
HTML+=$(HG_TOPICS:%=topic-%.html)
endif
ifdef HG_EXTENSIONS
HTML+=$(HG_EXTENSIONS:%=ext-%.html)
endif
all: man html all: man html
man: $(MAN) man: $(MAN)
html: $(HTML) html: $(HTML)
# This logic is duplicated in setup.py:hgbuilddoc() # This logic is duplicated in setup.py:hgbuilddoc()
common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt): $(GENDOC) common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt): $(GENDOC)
${PYTHON} gendoc.py "$(basename $@)" > $@.tmp ${PYTHON} gendoc.py "$(basename $@)" > $@.tmp
mv $@.tmp $@ mv $@.tmp $@
index.gendoc.txt: $(GENDOC)
$(PYTHON) gendoc.py index > $@.tmp
mv $@.tmp $@
%: %.txt %.gendoc.txt common.txt %: %.txt %.gendoc.txt common.txt
$(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \ $(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \
--strip-elements-with-class htmlonly $*.txt $* --strip-elements-with-class htmlonly $*.txt $*
%: %.gendoc.txt common.txt
$(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \
--strip-elements-with-class htmlonly $*.gendoc.txt $*
%.html: %.txt %.gendoc.txt common.txt %.html: %.txt %.gendoc.txt common.txt
$(PYTHON) runrst html $(RSTARGS) --halt warning \ $(PYTHON) runrst html $(RSTARGS) --halt warning \
--link-stylesheet --stylesheet-path style.css $*.txt $*.html --link-stylesheet --stylesheet-path style.css $*.txt $*.html
%.html: %.gendoc.txt common.txt
$(PYTHON) runrst html $(RSTARGS) --halt warning \
--link-stylesheet --stylesheet-path style.css $*.gendoc.txt $*.html
MANIFEST: man html MANIFEST: man html
# tracked files are already in the main MANIFEST # tracked files are already in the main MANIFEST
$(RM) $@ $(RM) $@
for i in $(MAN) $(HTML); do \ for i in $(MAN) $(HTML); do \
echo "doc/$$i" >> $@ ; \ echo "doc/$$i" >> $@ ; \
done done
install: man install: man
for i in $(MAN) ; do \ for i in $(MAN) ; do \
subdir=`echo $$i | sed -n 's/^.*\.\([0-9]\)$$/man\1/p'` ; \ subdir=`echo $$i | sed -n 's/^.*\.\([0-9]\)$$/man\1/p'` ; \
mkdir -p "$(DESTDIR)$(MANDIR)"/$$subdir ; \ mkdir -p "$(DESTDIR)$(MANDIR)"/$$subdir ; \
$(INSTALL) $$i "$(DESTDIR)$(MANDIR)"/$$subdir ; \ $(INSTALL) $$i "$(DESTDIR)$(MANDIR)"/$$subdir ; \
done done
clean: clean:
$(RM) $(MAN) $(HTML) common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt) MANIFEST $(RM) *[0-9] *.html common.txt commandlist.txt topiclist.txt extensionlist.txt $(SOURCES) MANIFEST CommandsTopicsExtensions.mk *.gendoc.txt

doc/gendoc.py

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, minirst.subsubsection) 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']) topics = findtopics(helptable, exclude=[b'config'])
helpprinter(ui, topics, minirst.section)
ui.write(minirst.section(_(b"Extensions"))) ui.write(minirst.section(_(b"Extensions")))
ui.write( ui.write(
_( _(
b"This section contains help for extensions that are " 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."
) )
commandprinter( commandprinter(
ui, ui,
cmdtable, cmdtable,
minirst.subsubsubsection, minirst.subsubsubsection,
minirst.subsubsubsubsection, minirst.subsubsubsubsection,
) )
def showtopic(ui, topic): def showcommandlist(ui):
# ui.verbose = True
cmdnames = allcommandnames(table, debugcmds=False)
for mainname, allnames in cmdnames.items():
ui.write(mainname)
ui.write(b" ")
def showtopiclist(ui):
for topic in helptable:
ui.write(topic[0][0])
ui.write(b" ")
def showextensionlist(ui):
for extensionname in allextensionnames():
ui.write(extensionname)
ui.write(b" ")
def showhelpindex(ui):
ui.write(minirst.section(_(b"Mercurial Distributed SCM")))
missingdoc = _(b"(no help text available)")
cats, h, syns = help._getcategorizedhelpcmds(ui, table, None)
ui.write(minirst.subsection(_(b"Commands")))
for cat in help.CATEGORY_ORDER:
catfns = sorted(cats.get(cat, []))
if not catfns:
continue
catname = gettext(help.CATEGORY_NAMES[cat])
ui.write(minirst.subsubsection(catname))
for c in catfns:
url = b'hg-%s.html' % c
ui.write(b" :`%s <%s>`__: %s" % (c, url, h[c]))
syns[c].remove(c)
if syns[c]:
ui.write(b" (aliases: *%s*)" % (b', '.join(syns[c])))
ui.write(b"\n")
ui.write(b"\n\n")
ui.write(b"\n\n")
ui.write(minirst.subsection(_(b"Additional Help Topics")))
topiccats, topicsyns = help._getcategorizedhelptopics(ui, helptable)
for cat in help.TOPIC_CATEGORY_ORDER:
topics = topiccats.get(cat, [])
if not topics:
continue
catname = gettext(help.TOPIC_CATEGORY_NAMES[cat])
ui.write(minirst.subsubsection(catname))
for t, desc in topics:
url = b'topic-%s.html' % t
ui.write(b" :`%s <%s>`__: %s" % (t, url, desc))
topicsyns[t].remove(t)
if topicsyns[t]:
ui.write(b" (aliases: *%s*)" % (b', '.join(topicsyns[t])))
ui.write(b"\n")
ui.write(b"\n\n")
ui.write(b"\n\n")
# Add an alphabetical list of extensions, categorized by group.
sectionkeywords = [
(b"(ADVANCED)", _(b"(ADVANCED)")),
(b"(EXPERIMENTAL)", _(b"(EXPERIMENTAL)")),
(b"(DEPRECATED)", _(b"(DEPRECATED)"))]
extensionsections = [
(b"Extensions", []),
(b"Advanced Extensions", []),
(b"Experimental Extensions", []),
(b"Deprecated Extensions", [])]
for extensionname in allextensionnames():
mod = extensions.load(ui, extensionname, None)
shortdoc, longdoc = _splitdoc(mod)
for i, kwds in enumerate(sectionkeywords):
if any([kwd in shortdoc for kwd in kwds]):
extensionsections[i+1][1].append(
(extensionname, mod, shortdoc))
break
else:
extensionsections[0][1].append(
(extensionname, mod, shortdoc))
for sectiontitle, extinfos in extensionsections:
ui.write(minirst.subsection(_(sectiontitle)))
for extinfo in sorted(extinfos, key=lambda ei: ei[0]):
extensionname, mod, shortdoc = extinfo
url = b'ext-%s.html' % extensionname
ui.write(minirst.subsubsection(
b'`%s <%s>`__' % (extensionname, url)))
ui.write(shortdoc)
ui.write(b'\n\n')
cmdtable = getattr(mod, 'cmdtable', None)
if cmdtable:
cmdnames = allcommandnames(cmdtable)
for f in sorted(cmdnames.keys()):
d = get_cmd(cmdnames[f], cmdtable)
ui.write(b':%s: ' % d[b'cmd'])
ui.write(d[b'desc'][0] or (missingdoc + b"\n"))
ui.write(b'\n')
ui.write(b'\n')
def showcommand(ui, mainname):
ui.verbose = True
cmdnames = allcommandnames(table, debugcmds=False)
allnames = cmdnames[mainname]
d = get_cmd(allnames, table)
header = _rendertpl(
'cmdheader.txt',
{'cmdname': mainname,
'cmdtitle': minirst.section(b'hg ' + mainname),
'cmdshortdesc': minirst.subsection(d[b'desc'][0]),
'cmdlongdesc': d[b'desc'][1],
'cmdsynopsis': d[b'synopsis']})
ui.write(header.encode())
_optionsprinter(ui, d, minirst.subsubsection)
if d[b'aliases']:
ui.write(minirst.subsubsection(_(b"Aliases")))
ui.write(b"::\n\n ")
ui.write(b", ".join(d[b'aliases']))
ui.write(b"\n")
def _splitdoc(obj):
objdoc = pycompat.getdoc(obj)
firstnl = objdoc.find(b'\n')
if firstnl > 0:
shortdoc = objdoc[:firstnl]
longdoc = objdoc[firstnl+1:]
else:
shortdoc = objdoc
longdoc = ''
return shortdoc, longdoc
def _rendertpl(tplname, data):
tplpath = os.path.join(os.path.dirname(__file__), 'templates', tplname)
with open(tplpath, 'r') as f:
tpl = f.read()
if isinstance(tpl, bytes):
tpl = tpl.decode()
for k in data:
data[k] = data[k].decode()
return tpl % data
def gettopicstable():
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"hgignore.5"],
b'', b'',
loaddoc(b'hgignore.5'), loaddoc(b'hgignore.5'),
help.TOPIC_CATEGORY_CONFIG, help.TOPIC_CATEGORY_CONFIG,
), ),
([b"hgrc.5"], b'', loaddoc(b'hgrc.5'), help.TOPIC_CATEGORY_CONFIG), ([b"hgrc.5"], b'', loaddoc(b'hgrc.5'), help.TOPIC_CATEGORY_CONFIG),
( (
[b"hg-ssh.8.gendoc"],
b'',
b'',
help.TOPIC_CATEGORY_CONFIG
),
(
[b"hgignore.5.gendoc"], [b"hgignore.5.gendoc"],
b'', b'',
loaddoc(b'hgignore'), loaddoc(b'hgignore'),
help.TOPIC_CATEGORY_CONFIG, help.TOPIC_CATEGORY_CONFIG,
), ),
( (
[b"hgrc.5.gendoc"], [b"hgrc.5.gendoc"],
b'', b'',
loaddoc(b'config'), loaddoc(b'config'),
help.TOPIC_CATEGORY_CONFIG, help.TOPIC_CATEGORY_CONFIG,
), ),
] ]
helpprinter(ui, helptable + extrahelptable, None, include=[topic]) return helptable + extrahelptable
def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]): def findtopics(helptable, include=[], exclude=[]):
found = []
for h in helptable: for h in helptable:
names, sec, doc = h[0:3] names, sec, doc = h[0:3]
if exclude and names[0] in exclude: if exclude and names[0] in exclude:
continue continue
if include and names[0] not in include: if include and names[0] not in include:
continue continue
found.append((names, sec, doc))
return found
def showtopic(ui, topic, wraptpl=False):
found = findtopics(gettopicstable(), include=[topic])
if not found:
raise Exception("ERROR: no such topic: %s\n" % topic)
ui.verbose = True
if wraptpl:
header = _rendertpl('topicheader.txt', {
'topicname': topic,
'topictitle': minirst.section(found[0][1])
})
ui.write(header.encode())
helpprinter(ui, found, None)
return True
def helpprinter(ui, topics, sectionfunc):
for h in topics:
names, sec, doc = h[0:3]
for name in names: for name in names:
ui.write(b".. _%s:\n" % name) ui.write(b".. _%s:\n" % name)
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 showextension(ui, extensionname):
mod = extensions.load(ui, extensionname, None)
ui.verbose = True
header = _rendertpl('extheader.txt', {
'extname': extensionname,
'exttitle': minirst.section(extensionname)
})
ui.write(header.encode())
shortdoc, longdoc = _splitdoc(mod)
ui.write(minirst.subsection(_(b"Description")))
ui.write(b"%s\n\n" % gettext(longdoc))
cmdtable = getattr(mod, 'cmdtable', None)
if cmdtable:
ui.write(minirst.subsection(_(b'Commands')))
commandprinter(ui, cmdtable, minirst.subsubsection, minirst.subsubsubsection)
def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc): def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
"""Render restructuredtext describing a list of commands and their """Render restructuredtext describing a list of commands and their
documentations, grouped by command category. documentations, grouped by command category.
Args: Args:
ui: UI object to write the output to ui: UI object to write the output to
cmdtable: a dict that maps a string of the command name plus its aliases 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 (separated with pipes) to a 3-tuple of (the command's function, a list
of its option descriptions, and a string summarizing available of its option descriptions, and a string summarizing available
options). Example, with aliases added for demonstration purposes: options). Example, with aliases added for demonstration purposes:
'phase|alias1|alias2': ( 'phase|alias1|alias2': (
<function phase at 0x7f0816b05e60>, <function phase at 0x7f0816b05e60>,
[ ('p', 'public', False, 'set changeset phase to public'), [ ('p', 'public', False, 'set changeset phase to public'),
..., ...,
('r', 'rev', [], 'target revision', 'REV')], ('r', 'rev', [], 'target revision', 'REV')],
'[-p|-d|-s] [-f] [-r] [REV...]' '[-p|-d|-s] [-f] [-r] [REV...]'
) )
sectionfunc: minirst function to format command category headers sectionfunc: minirst function to format command category headers
subsectionfunc: minirst function to format command headers subsectionfunc: minirst function to format command headers
""" """
h = {} cmdnames = allcommandnames(cmdtable)
for c, attr in cmdtable.items(): for f in sorted(cmdnames.keys()):
f = c.split(b"|")[0] d = get_cmd(cmdnames[f], cmdtable)
f = f.lstrip(b"^") _onecommandprinter(ui, d, sectionfunc)
h[f] = c
cmds = h.keys()
def helpcategory(cmd):
"""Given a canonical command name from `cmds` (above), retrieve its
help category. If helpcategory is None, default to CATEGORY_NONE.
"""
fullname = h[cmd]
details = cmdtable[fullname]
helpcategory = details[0].helpcategory
return helpcategory or help.registrar.command.CATEGORY_NONE
cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
for cmd in cmds:
# If a command category wasn't registered, the command won't get
# rendered below, so we raise an AssertionError.
if helpcategory(cmd) not in cmdsbycategory:
raise AssertionError(
"The following command did not register its (category) in "
"help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd))
)
cmdsbycategory[helpcategory(cmd)].append(cmd)
# Print the help for each command. We present the commands grouped by
# category, and we use help.CATEGORY_ORDER as a guide for a helpful order def _optionsprinter(ui, cmd, sectionfunc):
# in which to present the categories. opt_output = list(cmd[b'opts'])
for category in help.CATEGORY_ORDER:
categorycmds = cmdsbycategory[category]
if not categorycmds:
# Skip empty categories
continue
# Print a section header for the category.
# 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.
ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
# Print each command in the category
for f in sorted(categorycmds):
if f.startswith(b"debug"):
continue
d = get_cmd(h[f], cmdtable)
ui.write(subsectionfunc(d[b'cmd']))
# short description
ui.write(d[b'desc'][0])
# synopsis
ui.write(b"::\n\n")
synopsislines = d[b'synopsis'].splitlines()
for line in synopsislines:
# some commands (such as rebase) have a multi-line
# synopsis
ui.write(b" %s\n" % line)
ui.write(b'\n')
# description
ui.write(b"%s\n\n" % d[b'desc'][1])
# options
opt_output = list(d[b'opts'])
if opt_output: if opt_output:
opts_len = max([len(line[0]) for line in opt_output]) opts_len = max([len(line[0]) for line in opt_output])
ui.write(_(b"Options:\n\n")) ui.write(sectionfunc(_(b"Options")))
multioccur = False multioccur = False
for optstr, desc in opt_output: for optstr, desc in opt_output:
if desc: if desc:
s = b"%-*s %s" % (opts_len, optstr, desc) s = b"%-*s %s" % (opts_len, optstr, desc)
else: else:
s = optstr s = optstr
ui.write(b"%s\n" % s) ui.write(b"%s\n" % s)
if optstr.endswith(b"[+]>"): if optstr.endswith(b"[+]>"):
multioccur = True multioccur = True
if multioccur: if multioccur:
ui.write( ui.write(_(b"\n[+] marked option can be specified"
_( b" multiple times\n"))
b"\n[+] marked option can be specified"
b" multiple times\n"
)
)
ui.write(b"\n") ui.write(b"\n")
def _onecommandprinter(ui, cmd, sectionfunc):
ui.write(sectionfunc(cmd[b'cmd']))
# short description
ui.write(cmd[b'desc'][0])
# synopsis
ui.write(b"::\n\n")
synopsislines = cmd[b'synopsis'].splitlines()
for line in synopsislines:
# some commands (such as rebase) have a multi-line
# synopsis
ui.write(b" %s\n" % line)
ui.write(b'\n')
# description
ui.write(b"%s\n\n" % cmd[b'desc'][1])
# options
def _optsection(s):
return b"%s:\n\n" % s
_optionsprinter(ui, cmd, _optsection)
# aliases # aliases
if d[b'aliases']: if cmd[b'aliases']:
ui.write(_(b" aliases: %s\n\n") % b" ".join(d[b'aliases'])) ui.write(_(b" aliases: %s\n\n") % b" ".join(cmd[b'aliases']))
def allcommandnames(cmdtable, debugcmds=False):
allcmdnames = {}
for cmdnames, attr in cmdtable.items():
mainname = cmdnames.split(b"|")[0].lstrip(b"^")
if not debugcmds and mainname.startswith(b"debug"):
continue
allcmdnames[mainname] = cmdnames
return allcmdnames
def allextensionnames(): def allextensionnames():
return set(extensions.enabled().keys()) | set(extensions.disabled().keys()) return set(extensions.enabled().keys()) | set(extensions.disabled().keys())
if __name__ == "__main__": if __name__ == "__main__":
doc = b'hg.1.gendoc' doc = b'hg.1.gendoc'
if len(sys.argv) > 1: if len(sys.argv) > 1:
doc = encoding.strtolocal(sys.argv[1]) doc = encoding.strtolocal(sys.argv[1])
ui = uimod.ui.load() ui = uimod.ui.load()
if doc == b'hg.1.gendoc': if doc == b'commandlist':
showcommandlist(ui)
elif doc == b'topiclist':
showtopiclist(ui)
elif doc == b'extensionlist':
showextensionlist(ui)
elif doc == b'index':
showhelpindex(ui)
elif doc == b'hg.1.gendoc':
showdoc(ui) showdoc(ui)
elif doc.startswith(b'cmd-'):
showcommand(ui, doc[4:])
elif doc.startswith(b'topic-'):
showtopic(ui, doc[6:], wraptpl=True)
elif doc.startswith(b'ext-'):
showextension(ui, doc[4:])
else: else:
showtopic(ui, encoding.strtolocal(sys.argv[1])) showtopic(ui, doc)

doc/templates/cmdheader.txt

  • This file was added.
.. _hg-%(cmdname)s.1:
%(cmdtitle)s
%(cmdshortdesc)s
.. contents::
:backlinks: top
:class: htmlonly
:depth: 1
Synopsis
--------
::
%(cmdsynopsis)s
Description
-----------
%(cmdlongdesc)s

doc/templates/extheader.txt

  • This file was added.
.. _ext-%(extname)s:
%(exttitle)s

doc/templates/topicheader.txt

  • This file was added.
.. _topic-%(topicname)s:
%(topictitle)s