help.py
208 lines
| 7.6 KiB
| text/x-python
|
PythonLexer
/ mercurial / help.py
Matt Mackall
|
r3795 | # help.py - help data for mercurial | ||
# | ||||
# Copyright 2006 Matt Mackall <mpm@selenic.com> | ||||
# | ||||
Martin Geisler
|
r8225 | # This software may be used and distributed according to the terms of the | ||
Matt Mackall
|
r10263 | # GNU General Public License version 2 or any later version. | ||
Matt Mackall
|
r3795 | |||
Martin Geisler
|
r9539 | from i18n import gettext, _ | ||
Augie Fackler
|
r16710 | import itertools, sys, os | ||
FUJIWARA Katsunori
|
r16126 | import extensions, revset, fileset, templatekw, templatefilters, filemerge | ||
Olav Reinert
|
r16781 | import encoding, util, minirst | ||
Cédric Duval
|
r8863 | |||
Matt Mackall
|
r14316 | def listexts(header, exts, indent=1): | ||
Cédric Duval
|
r8879 | '''return a text listing of the given extensions''' | ||
Olav Reinert
|
r16852 | rst = [] | ||
if exts: | ||||
rst.append('\n%s\n\n' % header) | ||||
for name, desc in sorted(exts.iteritems()): | ||||
rst.append('%s:%s: %s\n' % (' ' * indent, name, desc)) | ||||
return rst | ||||
Cédric Duval
|
r8864 | |||
Cédric Duval
|
r8879 | def extshelp(): | ||
Olav Reinert
|
r16852 | rst = loaddoc('extensions')().splitlines(True) | ||
rst.extend(listexts(_('enabled extensions:'), extensions.enabled())) | ||||
rst.extend(listexts(_('disabled extensions:'), extensions.disabled())) | ||||
doc = ''.join(rst) | ||||
Cédric Duval
|
r8863 | return doc | ||
Martin Geisler
|
r7013 | |||
Olav Reinert
|
r16781 | def optrst(options, verbose): | ||
data = [] | ||||
multioccur = False | ||||
for option in options: | ||||
if len(option) == 5: | ||||
shortopt, longopt, default, desc, optlabel = option | ||||
else: | ||||
shortopt, longopt, default, desc = option | ||||
optlabel = _("VALUE") # default label | ||||
if _("DEPRECATED") in desc and not verbose: | ||||
continue | ||||
so = '' | ||||
if shortopt: | ||||
so = '-' + shortopt | ||||
lo = '--' + longopt | ||||
if default: | ||||
desc += _(" (default: %s)") % default | ||||
if isinstance(default, list): | ||||
lo += " %s [+]" % optlabel | ||||
multioccur = True | ||||
elif (default is not None) and not isinstance(default, bool): | ||||
lo += " %s" % optlabel | ||||
data.append((so, lo, desc)) | ||||
rst = minirst.maketable(data, 1) | ||||
if multioccur: | ||||
Olav Reinert
|
r16815 | rst.append(_("\n[+] marked option can be specified multiple times\n")) | ||
Olav Reinert
|
r16781 | |||
Olav Reinert
|
r16815 | return ''.join(rst) | ||
Olav Reinert
|
r16781 | |||
FUJIWARA Katsunori
|
r17837 | def indicateomitted(rst, omitted, notomitted=None): | ||
rst.append('\n\n.. container:: omitted\n\n %s\n\n' % omitted) | ||||
if notomitted: | ||||
rst.append('\n\n.. container:: notomitted\n\n %s\n\n' % notomitted) | ||||
Augie Fackler
|
r16710 | def topicmatch(kw): | ||
"""Return help topics matching kw. | ||||
Returns {'section': [(name, summary), ...], ...} where section is | ||||
one of topics, commands, extensions, or extensioncommands. | ||||
""" | ||||
kw = encoding.lower(kw) | ||||
def lowercontains(container): | ||||
Nikolaj Sjujskij
|
r16845 | return kw in encoding.lower(container) # translated in helptable | ||
Augie Fackler
|
r16710 | results = {'topics': [], | ||
'commands': [], | ||||
'extensions': [], | ||||
'extensioncommands': [], | ||||
} | ||||
for names, header, doc in helptable: | ||||
if (sum(map(lowercontains, names)) | ||||
or lowercontains(header) | ||||
or lowercontains(doc())): | ||||
results['topics'].append((names[0], header)) | ||||
import commands # avoid cycle | ||||
for cmd, entry in commands.table.iteritems(): | ||||
if cmd.startswith('debug'): | ||||
continue | ||||
if len(entry) == 3: | ||||
summary = entry[2] | ||||
else: | ||||
summary = '' | ||||
Nikolaj Sjujskij
|
r16845 | # translate docs *before* searching there | ||
docs = _(getattr(entry[0], '__doc__', None)) or '' | ||||
Augie Fackler
|
r16710 | if kw in cmd or lowercontains(summary) or lowercontains(docs): | ||
Nikolaj Sjujskij
|
r16845 | doclines = docs.splitlines() | ||
Augie Fackler
|
r16710 | if doclines: | ||
summary = doclines[0] | ||||
cmdname = cmd.split('|')[0].lstrip('^') | ||||
results['commands'].append((cmdname, summary)) | ||||
for name, docs in itertools.chain( | ||||
extensions.enabled().iteritems(), | ||||
extensions.disabled().iteritems()): | ||||
# extensions.load ignores the UI argument | ||||
mod = extensions.load(None, name, '') | ||||
if lowercontains(name) or lowercontains(docs): | ||||
Nikolaj Sjujskij
|
r16845 | # extension docs are already translated | ||
results['extensions'].append((name, docs.splitlines()[0])) | ||||
Augie Fackler
|
r16710 | for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems(): | ||
Augie Fackler
|
r16711 | if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])): | ||
Augie Fackler
|
r16710 | cmdname = cmd.split('|')[0].lstrip('^') | ||
Olav Reinert
|
r16942 | if entry[0].__doc__: | ||
cmddoc = gettext(entry[0].__doc__).splitlines()[0] | ||||
Thomas Arendsen Hein
|
r16884 | else: | ||
cmddoc = _('(no help text available)') | ||||
results['extensioncommands'].append((cmdname, cmddoc)) | ||||
Augie Fackler
|
r16710 | return results | ||
Martin Geisler
|
r9539 | def loaddoc(topic): | ||
"""Return a delayed loader for help/topic.txt.""" | ||||
Matt Mackall
|
r3798 | |||
Martin Geisler
|
r9539 | def loader(): | ||
Augie Fackler
|
r14941 | if util.mainfrozen(): | ||
Martin Geisler
|
r9539 | module = sys.executable | ||
else: | ||||
module = __file__ | ||||
base = os.path.dirname(module) | ||||
Dirkjan Ochtman
|
r7293 | |||
Martin Geisler
|
r9539 | for dir in ('.', '..'): | ||
docdir = os.path.join(base, dir, 'help') | ||||
if os.path.isdir(docdir): | ||||
break | ||||
Alexander Solovyov
|
r7677 | |||
Martin Geisler
|
r9539 | path = os.path.join(docdir, topic + ".txt") | ||
Dan Villiom Podlaski Christiansen
|
r14168 | doc = gettext(util.readfile(path)) | ||
Patrick Mezard
|
r12820 | for rewriter in helphooks.get(topic, []): | ||
doc = rewriter(topic, doc) | ||||
return doc | ||||
Martin Geisler
|
r9539 | return loader | ||
Alexander Solovyov
|
r7677 | |||
Yun Lee
|
r13888 | helptable = sorted([ | ||
Martin Geisler
|
r12145 | (["config", "hgrc"], _("Configuration Files"), loaddoc('config')), | ||
Martin Geisler
|
r9539 | (["dates"], _("Date Formats"), loaddoc('dates')), | ||
(["patterns"], _("File Name Patterns"), loaddoc('patterns')), | ||||
Matt Mackall
|
r10282 | (['environment', 'env'], _('Environment Variables'), | ||
loaddoc('environment')), | ||||
Mads Kiilerich
|
r17322 | (['revisions', 'revs'], _('Specifying Single Revisions'), | ||
Matt Mackall
|
r10282 | loaddoc('revisions')), | ||
Mads Kiilerich
|
r17322 | (['multirevs', 'mrevs'], _('Specifying Multiple Revisions'), | ||
Matt Mackall
|
r10282 | loaddoc('multirevs')), | ||
Mads Kiilerich
|
r17322 | (['revsets', 'revset'], _("Specifying Revision Sets"), loaddoc('revsets')), | ||
(['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')), | ||||
Martin Geisler
|
r9539 | (['diffs'], _('Diff Formats'), loaddoc('diffs')), | ||
Mads Kiilerich
|
r17323 | (['merge-tools', 'mergetools'], _('Merge Tools'), loaddoc('merge-tools')), | ||
A. S. Budden
|
r16568 | (['templating', 'templates', 'template', 'style'], _('Template Usage'), | ||
Matt Mackall
|
r10282 | loaddoc('templates')), | ||
Martin Geisler
|
r9539 | (['urls'], _('URL Paths'), loaddoc('urls')), | ||
Martin Geisler
|
r16547 | (["extensions"], _("Using Additional Features"), extshelp), | ||
Mads Kiilerich
|
r17322 | (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')), | ||
Mads Kiilerich
|
r17321 | (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')), | ||
(["glossary"], _("Glossary"), loaddoc('glossary')), | ||||
(["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"), | ||||
loaddoc('hgignore')), | ||||
(["phases"], _("Working with Phases"), loaddoc('phases')), | ||||
Yun Lee
|
r13888 | ]) | ||
Patrick Mezard
|
r12820 | |||
# Map topics to lists of callable taking the current topic help and | ||||
# returning the updated version | ||||
Matt Mackall
|
r14318 | helphooks = {} | ||
Patrick Mezard
|
r12820 | |||
def addtopichook(topic, rewriter): | ||||
helphooks.setdefault(topic, []).append(rewriter) | ||||
Patrick Mezard
|
r13593 | |||
def makeitemsdoc(topic, doc, marker, items): | ||||
"""Extract docstring from the items key to function mapping, build a | ||||
.single documentation block and use it to overwrite the marker in doc | ||||
""" | ||||
entries = [] | ||||
for name in sorted(items): | ||||
text = (items[name].__doc__ or '').rstrip() | ||||
if not text: | ||||
continue | ||||
text = gettext(text) | ||||
lines = text.splitlines() | ||||
"Yann E. MORIN"
|
r16250 | doclines = [(lines[0])] | ||
for l in lines[1:]: | ||||
# Stop once we find some Python doctest | ||||
if l.strip().startswith('>>>'): | ||||
break | ||||
doclines.append(' ' + l.strip()) | ||||
entries.append('\n'.join(doclines)) | ||||
Patrick Mezard
|
r13593 | entries = '\n\n'.join(entries) | ||
return doc.replace(marker, entries) | ||||
Matt Mackall
|
r14318 | |||
def addtopicsymbols(topic, marker, symbols): | ||||
def add(topic, doc): | ||||
return makeitemsdoc(topic, doc, marker, symbols) | ||||
addtopichook(topic, add) | ||||
Matt Mackall
|
r14686 | addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols) | ||
FUJIWARA Katsunori
|
r16126 | addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals) | ||
Matt Mackall
|
r14318 | addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols) | ||
epriestley
|
r17187 | addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords) | ||
Matt Mackall
|
r14318 | addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters) | ||