This is an archive of the discontinued Mercurial Phabricator instance.

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

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

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:

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?
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?
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!

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.

@ludovicchabant gentle ping

@ludovicchabant gentle re-ping

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

		Path
M		.hgignore (11 lines)
M		doc/Makefile (104 lines)
M		doc/gendoc.py (362 lines)
A	M	doc/templates/cmdheader.txt (22 lines)
A	M	doc/templates/extheader.txt (4 lines)
A	M	doc/templates/topicheader.txt (4 lines)

Commit	Parents	Author	Summary	Date
254b3dbd26af	f26a94873f75	Ludovic Chabant		Sep 30 2020, 5:33 PM

	Status	Author	Revision
	Needs Revision	ludovicchabant	D9135 doc: Generate separate commands/topics/extension web pages.
	Closed	ludovicchabant	D9134 help: extract logic for listing commands and topics.

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

Diff	ID	Base	Description	Created	Lint	Unit
Base			Base
Diff 1	22957			Sep 30 2020, 5:35 PM	★	★

This is an archive of the discontinued Mercurial Phabricator instance.

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

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List