( )⚙ D5068 help: assigning topic categories

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D5068

help: assigning topic categories
ClosedPublic

Authored by rdamazio on Oct 13 2018, 6:19 AM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHGfabbf9310025: help: assigning topic categories
Summary

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

rdamazio created this revision.Oct 13 2018, 6:19 AM
rdamazio updated this revision to Diff 12042.Oct 13 2018, 6:44 AM
rdamazio updated this revision to Diff 12063.Oct 13 2018, 8:44 AM
rdamazio updated this revision to Diff 12123.Oct 14 2018, 6:32 AM
Closed by commit rHGfabbf9310025: help: assigning topic categories (authored by rdamazio). · Explain WhyOct 14 2018, 11:16 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mdoc/gendoc.py (15 lines)
Mmercurial/help.py (75 lines)
Mtests/test-globalopts.t (80 lines)
Mtests/test-help.t (120 lines)

Diff 12123

doc/gendoc.py

ui.write("%s\n\n" % gettext(mod.__doc__)) ui.write("%s\n\n" % gettext(mod.__doc__))
cmdtable = getattr(mod, 'cmdtable', None) cmdtable = getattr(mod, 'cmdtable', None)
if cmdtable: if cmdtable:
ui.write(minirst.subsubsection(_('Commands'))) ui.write(minirst.subsubsection(_('Commands')))
commandprinter(ui, cmdtable, minirst.subsubsubsection) commandprinter(ui, cmdtable, minirst.subsubsubsection)
def showtopic(ui, topic): def showtopic(ui, topic):
extrahelptable = [ extrahelptable = [
(["common"], '', loaddoc('common')), (["common"], '', loaddoc('common'), help.TOPIC_CATEGORY_MISC),
(["hg.1"], '', loaddoc('hg.1')), (["hg.1"], '', loaddoc('hg.1'), help.TOPIC_CATEGORY_CONFIG),
(["hg-ssh.8"], '', loaddoc('hg-ssh.8')), (["hg-ssh.8"], '', loaddoc('hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG),
(["hgignore.5"], '', loaddoc('hgignore.5')), (["hgignore.5"], '', loaddoc('hgignore.5'), help.TOPIC_CATEGORY_CONFIG),
(["hgrc.5"], '', loaddoc('hgrc.5')), (["hgrc.5"], '', loaddoc('hgrc.5'), help.TOPIC_CATEGORY_CONFIG),
(["hgignore.5.gendoc"], '', loaddoc('hgignore')), (["hgignore.5.gendoc"], '', loaddoc('hgignore'),
(["hgrc.5.gendoc"], '', loaddoc('config')), help.TOPIC_CATEGORY_CONFIG),
(["hgrc.5.gendoc"], '', loaddoc('config'), help.TOPIC_CATEGORY_CONFIG),
] ]
helpprinter(ui, helptable + extrahelptable, None, include=[topic]) helpprinter(ui, helptable + extrahelptable, None, include=[topic])
def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]): def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
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

mercurial/help.py

registrar.command.CATEGORY_IMPORT_EXPORT: 'Change import/export', registrar.command.CATEGORY_IMPORT_EXPORT: 'Change import/export',
registrar.command.CATEGORY_MAINTENANCE: 'Repository maintenance', registrar.command.CATEGORY_MAINTENANCE: 'Repository maintenance',
registrar.command.CATEGORY_HELP: 'Help', registrar.command.CATEGORY_HELP: 'Help',
registrar.command.CATEGORY_MISC: 'Miscellaneous commands', registrar.command.CATEGORY_MISC: 'Miscellaneous commands',
registrar.command.CATEGORY_NONE: 'Uncategorized commands', registrar.command.CATEGORY_NONE: 'Uncategorized commands',
} }
# Topic categories. # Topic categories.
TOPIC_CATEGORY_IDS = 'ids'
TOPIC_CATEGORY_OUTPUT = 'output'
TOPIC_CATEGORY_CONFIG = 'config'
TOPIC_CATEGORY_CONCEPTS = 'concepts'
TOPIC_CATEGORY_MISC = 'misc'
TOPIC_CATEGORY_NONE = 'none' TOPIC_CATEGORY_NONE = 'none'
# The order in which topic categories will be displayed. # The order in which topic categories will be displayed.
# Extensions with custom categories should insert them into this list # Extensions with custom categories should insert them into this list
# after/before the appropriate item, rather than replacing the list or # after/before the appropriate item, rather than replacing the list or
# assuming absolute positions. # assuming absolute positions.
TOPIC_CATEGORY_ORDER = [ TOPIC_CATEGORY_ORDER = [
TOPIC_CATEGORY_IDS,
TOPIC_CATEGORY_OUTPUT,
TOPIC_CATEGORY_CONFIG,
TOPIC_CATEGORY_CONCEPTS,
TOPIC_CATEGORY_MISC,
TOPIC_CATEGORY_NONE, TOPIC_CATEGORY_NONE,
] ]
# Human-readable topic category names. These are translated. # Human-readable topic category names. These are translated.
TOPIC_CATEGORY_NAMES = { TOPIC_CATEGORY_NAMES = {
TOPIC_CATEGORY_IDS: 'Mercurial identifiers',
TOPIC_CATEGORY_OUTPUT: 'Mercurial output',
TOPIC_CATEGORY_CONFIG: 'Mercurial configuration',
TOPIC_CATEGORY_CONCEPTS: 'Concepts',
TOPIC_CATEGORY_MISC: 'Miscellaneous',
TOPIC_CATEGORY_NONE: 'Uncategorized topics',
TOPIC_CATEGORY_NONE: 'Uncategorized topics', TOPIC_CATEGORY_NONE: 'Uncategorized topics',
} }
def listexts(header, exts, indent=1, showdeprecated=False): def listexts(header, exts, indent=1, showdeprecated=False):
'''return a text listing of the given extensions''' '''return a text listing of the given extensions'''
rst = [] rst = []
if exts: if exts:
for name, desc in sorted(exts.iteritems()): for name, desc in sorted(exts.iteritems()):
lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n', lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n',
'\n'] '\n']
for names, header, doc in internalstable: for names, header, doc in internalstable:
lines.append(' :%s: %s\n' % (names[0], header)) lines.append(' :%s: %s\n' % (names[0], header))
return ''.join(lines) return ''.join(lines)
helptable = sorted([ helptable = sorted([
(['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')), (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec'),
(['color'], _("Colorizing Outputs"), loaddoc('color')), TOPIC_CATEGORY_CONCEPTS),
(["config", "hgrc"], _("Configuration Files"), loaddoc('config')), (['color'], _("Colorizing Outputs"), loaddoc('color'),
(['deprecated'], _("Deprecated Features"), loaddoc('deprecated')), TOPIC_CATEGORY_OUTPUT),
(["dates"], _("Date Formats"), loaddoc('dates')), (["config", "hgrc"], _("Configuration Files"), loaddoc('config'),
(["flags"], _("Command-line flags"), loaddoc('flags')), TOPIC_CATEGORY_CONFIG),
(["patterns"], _("File Name Patterns"), loaddoc('patterns')), (['deprecated'], _("Deprecated Features"), loaddoc('deprecated'),
TOPIC_CATEGORY_MISC),
(["dates"], _("Date Formats"), loaddoc('dates'), TOPIC_CATEGORY_OUTPUT),
(["flags"], _("Command-line flags"), loaddoc('flags'),
TOPIC_CATEGORY_CONFIG),
(["patterns"], _("File Name Patterns"), loaddoc('patterns'),
TOPIC_CATEGORY_IDS),
(['environment', 'env'], _('Environment Variables'), (['environment', 'env'], _('Environment Variables'),
loaddoc('environment')), loaddoc('environment'), TOPIC_CATEGORY_CONFIG),
(['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'], (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
_('Specifying Revisions'), loaddoc('revisions')), _('Specifying Revisions'), loaddoc('revisions'), TOPIC_CATEGORY_IDS),
(['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')), (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets'),
(['diffs'], _('Diff Formats'), loaddoc('diffs')), TOPIC_CATEGORY_IDS),
(['diffs'], _('Diff Formats'), loaddoc('diffs'), TOPIC_CATEGORY_OUTPUT),
(['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'), (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
loaddoc('merge-tools')), loaddoc('merge-tools'), TOPIC_CATEGORY_CONFIG),
(['templating', 'templates', 'template', 'style'], _('Template Usage'), (['templating', 'templates', 'template', 'style'], _('Template Usage'),
loaddoc('templates')), loaddoc('templates'), TOPIC_CATEGORY_OUTPUT),
(['urls'], _('URL Paths'), loaddoc('urls')), (['urls'], _('URL Paths'), loaddoc('urls'), TOPIC_CATEGORY_IDS),
(["extensions"], _("Using Additional Features"), extshelp), (["extensions"], _("Using Additional Features"), extshelp,
(["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')), TOPIC_CATEGORY_CONFIG),
(["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')), (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos'),
(["glossary"], _("Glossary"), loaddoc('glossary')), TOPIC_CATEGORY_CONCEPTS),
(["hgweb"], _("Configuring hgweb"), loaddoc('hgweb'),
TOPIC_CATEGORY_CONFIG),
(["glossary"], _("Glossary"), loaddoc('glossary'), TOPIC_CATEGORY_CONCEPTS),
(["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"), (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
loaddoc('hgignore')), loaddoc('hgignore'), TOPIC_CATEGORY_IDS),
(["phases"], _("Working with Phases"), loaddoc('phases')), (["phases"], _("Working with Phases"), loaddoc('phases'),
TOPIC_CATEGORY_CONCEPTS),
(['scripting'], _('Using Mercurial from scripts and automation'), (['scripting'], _('Using Mercurial from scripts and automation'),
loaddoc('scripting')), loaddoc('scripting'), TOPIC_CATEGORY_MISC),
(['internals'], _("Technical implementation topics"), (['internals'], _("Technical implementation topics"), internalshelp,
internalshelp), TOPIC_CATEGORY_MISC),
(['pager'], _("Pager Support"), loaddoc('pager')), (['pager'], _("Pager Support"), loaddoc('pager'), TOPIC_CATEGORY_CONFIG),
]) ])
# Maps topics with sub-topics to a list of their sub-topics. # Maps topics with sub-topics to a list of their sub-topics.
subtopics = { subtopics = {
'internals': internalstable, 'internals': internalstable,
} }
# Map topics to lists of callable taking the current topic help and # Map topics to lists of callable taking the current topic help and

tests/test-globalopts.t

Help: Help:
config show combined config settings from all hgrc files config show combined config settings from all hgrc files
help show help for a given topic or a help overview help show help for a given topic or a help overview
version output version and copyright information version output version and copyright information
additional help topics: additional help topics:
bundlespec Bundle File Formats Mercurial identifiers:
filesets Specifying File Sets
hgignore Syntax for Mercurial Ignore Files
patterns File Name Patterns
revisions Specifying Revisions
urls URL Paths
Mercurial output:
color Colorizing Outputs color Colorizing Outputs
config Configuration Files
dates Date Formats dates Date Formats
deprecated Deprecated Features
diffs Diff Formats diffs Diff Formats
templating Template Usage
Mercurial configuration:
config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets
flags Command-line flags flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns
Concepts:
bundlespec Bundle File Formats
glossary Glossary
phases Working with Phases phases Working with Phases
revisions Specifying Revisions
scripting Using Mercurial from scripts and automation
subrepos Subrepositories subrepos Subrepositories
templating Template Usage
urls URL Paths Miscellaneous:
deprecated Deprecated Features
internals Technical implementation topics
scripting Using Mercurial from scripts and automation
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)
$ hg --help $ hg --help
Mercurial Distributed SCM Mercurial Distributed SCM
list of commands: list of commands:
Help: Help:
config show combined config settings from all hgrc files config show combined config settings from all hgrc files
help show help for a given topic or a help overview help show help for a given topic or a help overview
version output version and copyright information version output version and copyright information
additional help topics: additional help topics:
bundlespec Bundle File Formats Mercurial identifiers:
filesets Specifying File Sets
hgignore Syntax for Mercurial Ignore Files
patterns File Name Patterns
revisions Specifying Revisions
urls URL Paths
Mercurial output:
color Colorizing Outputs color Colorizing Outputs
config Configuration Files
dates Date Formats dates Date Formats
deprecated Deprecated Features
diffs Diff Formats diffs Diff Formats
templating Template Usage
Mercurial configuration:
config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets
flags Command-line flags flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns
Concepts:
bundlespec Bundle File Formats
glossary Glossary
phases Working with Phases phases Working with Phases
revisions Specifying Revisions
scripting Using Mercurial from scripts and automation
subrepos Subrepositories subrepos Subrepositories
templating Template Usage
urls URL Paths Miscellaneous:
deprecated Deprecated Features
internals Technical implementation topics
scripting Using Mercurial from scripts and automation
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)
#endif #endif
Not tested: --debugger Not tested: --debugger

tests/test-help.t

Help: Help:
config show combined config settings from all hgrc files config show combined config settings from all hgrc files
help show help for a given topic or a help overview help show help for a given topic or a help overview
version output version and copyright information version output version and copyright information
additional help topics: additional help topics:
bundlespec Bundle File Formats Mercurial identifiers:
filesets Specifying File Sets
hgignore Syntax for Mercurial Ignore Files
patterns File Name Patterns
revisions Specifying Revisions
urls URL Paths
Mercurial output:
color Colorizing Outputs color Colorizing Outputs
config Configuration Files
dates Date Formats dates Date Formats
deprecated Deprecated Features
diffs Diff Formats diffs Diff Formats
templating Template Usage
Mercurial configuration:
config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets
flags Command-line flags flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns
Concepts:
bundlespec Bundle File Formats
glossary Glossary
phases Working with Phases phases Working with Phases
revisions Specifying Revisions
scripting Using Mercurial from scripts and automation
subrepos Subrepositories subrepos Subrepositories
templating Template Usage
urls URL Paths Miscellaneous:
deprecated Deprecated Features
internals Technical implementation topics
scripting Using Mercurial from scripts and automation
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)
$ hg -q help $ hg -q help
Repository creation: Repository creation:
clone make a copy of an existing repository clone make a copy of an existing repository
init create a new repository in the given directory init create a new repository in the given directory
Help: Help:
config show combined config settings from all hgrc files config show combined config settings from all hgrc files
help show help for a given topic or a help overview help show help for a given topic or a help overview
version output version and copyright information version output version and copyright information
additional help topics: additional help topics:
bundlespec Bundle File Formats Mercurial identifiers:
filesets Specifying File Sets
hgignore Syntax for Mercurial Ignore Files
patterns File Name Patterns
revisions Specifying Revisions
urls URL Paths
Mercurial output:
color Colorizing Outputs color Colorizing Outputs
config Configuration Files
dates Date Formats dates Date Formats
deprecated Deprecated Features
diffs Diff Formats diffs Diff Formats
templating Template Usage
Mercurial configuration:
config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets
flags Command-line flags flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns
Concepts:
bundlespec Bundle File Formats
glossary Glossary
phases Working with Phases phases Working with Phases
revisions Specifying Revisions
scripting Using Mercurial from scripts and automation
subrepos Subrepositories subrepos Subrepositories
templating Template Usage
urls URL Paths Miscellaneous:
deprecated Deprecated Features
internals Technical implementation topics
scripting Using Mercurial from scripts and automation
Test extension help: Test extension help:
$ hg help extensions --config extensions.rebase= --config extensions.children= $ hg help extensions --config extensions.rebase= --config extensions.children=
Using Additional Features Using Additional Features
""""""""""""""""""""""""" """""""""""""""""""""""""
Mercurial has the ability to add new features through the use of Mercurial has the ability to add new features through the use of
extensions. Extensions may add new commands, add options to existing extensions. Extensions may add new commands, add options to existing
version output version and copyright information version output version and copyright information
enabled extensions: enabled extensions:
helpext (no help text available) helpext (no help text available)
additional help topics: additional help topics:
bundlespec Bundle File Formats Mercurial identifiers:
filesets Specifying File Sets
hgignore Syntax for Mercurial Ignore Files
patterns File Name Patterns
revisions Specifying Revisions
urls URL Paths
Mercurial output:
color Colorizing Outputs color Colorizing Outputs
config Configuration Files
dates Date Formats dates Date Formats
deprecated Deprecated Features
diffs Diff Formats diffs Diff Formats
templating Template Usage
Mercurial configuration:
config Configuration Files
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets
flags Command-line flags flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns
Concepts:
bundlespec Bundle File Formats
glossary Glossary
phases Working with Phases phases Working with Phases
revisions Specifying Revisions
scripting Using Mercurial from scripts and automation
subrepos Subrepositories subrepos Subrepositories
templating Template Usage
urls URL Paths Miscellaneous:
deprecated Deprecated Features
internals Technical implementation topics
scripting Using Mercurial from scripts and automation
(use 'hg help -v' to show built-in aliases and global options) (use 'hg help -v' to show built-in aliases and global options)
#endif #endif
Test list of internal help commands Test list of internal help commands
$ hg help debug $ hg help debug