Mercurial > public > mercurial-scm > hg-stable

annotate mercurial/help.py @ 14316:d5b525697ddb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
extensions: drop maxlength from enabled and disabled This is a bad/silly API. Instead calculate maxlength in one place in help it's used and simplify all the callers.
author Matt Mackall <mpm@selenic.com>
date Fri, 13 May 2011 11:04:51 -0500
parents 135e244776f0
children 660b0c1b6196
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
1 # help.py - help data for mercurial
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
2 #
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
3 # Copyright 2006 Matt Mackall <mpm@selenic.com>
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
4 #
8225
46293a0c7e9f updated license to be explicit about GPL version 2
Martin Geisler <mg@lazybytes.net>
parents: 8159
diff changeset
5 # This software may be used and distributed according to the terms of the
10263
25e572394f5c Update license to GPLv2+
Matt Mackall <mpm@selenic.com>
parents: 9785
diff changeset
6 # GNU General Public License version 2 or any later version.
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
7
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
8 from i18n import gettext, _
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
9 import sys, os
9678
e2b1de5fee04 remove unused imports
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents: 9539
diff changeset
10 import extensions
14168
135e244776f0 prevent transient leaks of file handle by using new helper functions
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 14044
diff changeset
11 import util
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
12
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
13
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
14 def moduledoc(file):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
15 '''return the top-level python documentation for the given file
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
16
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
17 Loosely inspired by pydoc.source_synopsis(), but rewritten to
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
18 handle triple quotes and to return the whole text instead of just
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
19 the synopsis'''
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
20 result = []
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
21
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
22 line = file.readline()
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
23 while line[:1] == '#' or not line.strip():
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
24 line = file.readline()
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
25 if not line:
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
26 break
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
27
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
28 start = line[:3]
12401
4cdaf1adafc8 backout most of 4f8067c94729
Matt Mackall <mpm@selenic.com>
parents: 12387
diff changeset
29 if start == '"""' or start == "'''":
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
30 line = line[3:]
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
31 while line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
32 if line.rstrip().endswith(start):
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
33 line = line.split(start)[0]
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
34 if line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
35 result.append(line)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
36 break
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
37 elif not line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
38 return None # unmatched delimiter
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
39 result.append(line)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
40 line = file.readline()
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
41 else:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
42 return None
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
43
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
44 return ''.join(result)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
45
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
46 def listexts(header, exts, indent=1):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
47 '''return a text listing of the given extensions'''
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
48 if not exts:
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
49 return ''
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
50 maxlength = max(len(e) for e in exts)
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
51 result = '\n%s\n\n' % header
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
52 for name, desc in sorted(exts.iteritems()):
10364
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
53 result += '%s%-*s %s\n' % (' ' * indent, maxlength + 2,
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
54 ':%s:' % name, desc)
8864
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
C?dric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
55 return result
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
C?dric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
56
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
57 def extshelp():
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
58 doc = loaddoc('extensions')()
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
59 doc += listexts(_('enabled extensions:'), extensions.enabled())
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 14168
diff changeset
60 doc += listexts(_('disabled extensions:'), extensions.disabled())
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
61 return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
62
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
63 def loaddoc(topic):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
64 """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
65
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
66 def loader():
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
67 if hasattr(sys, 'frozen'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
68 module = sys.executable
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
69 else:
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
70 module = __file__
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
71 base = os.path.dirname(module)
7293
3549659450e6 help: add a topic on git diffs (issue1352)
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 7013
diff changeset
72
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
73 for dir in ('.', '..'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
74 docdir = os.path.join(base, dir, 'help')
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
75 if os.path.isdir(docdir):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
76 break
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
77
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
78 path = os.path.join(docdir, topic + ".txt")
14168
135e244776f0 prevent transient leaks of file handle by using new helper functions
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 14044
diff changeset
79 doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
80 for rewriter in helphooks.get(topic, []):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
81 doc = rewriter(topic, doc)
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
82 return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
83
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
84 return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
85
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
86 helptable = sorted([
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
87 (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
88 (["dates"], _("Date Formats"), loaddoc('dates')),
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
89 (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
90 (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
91 loaddoc('environment')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
92 (['revs', 'revisions'], _('Specifying Single Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
93 loaddoc('revisions')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
94 (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
95 loaddoc('multirevs')),
12818
019b8e1e0402 help: add "revset" alias for "revsets" help topic
Martin Geisler <mg@lazybytes.net>
parents: 12771
diff changeset
96 (['revset', 'revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
97 (['diffs'], _('Diff Formats'), loaddoc('diffs')),
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents: 12401
diff changeset
98 (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
99 (['templating', 'templates'], _('Template Usage'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
100 loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
101 (['urls'], _('URL Paths'), loaddoc('urls')),
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
102 (["extensions"], _("Using additional features"), extshelp),
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
103 (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos')),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
104 (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
105 (["glossary"], _("Glossary"), loaddoc('glossary')),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
106 (["hgignore", "ignore"], _("syntax for Mercurial ignore files"),
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents: 13888
diff changeset
107 loaddoc('hgignore')),
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
108 ])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
109
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
110 # Map topics to lists of callable taking the current topic help and
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
111 # returning the updated version
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
112 helphooks = {
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
113 }
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
114
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
115 def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
116 helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
117
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
118 def makeitemsdoc(topic, doc, marker, items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
119 """Extract docstring from the items key to function mapping, build a
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
120 .single documentation block and use it to overwrite the marker in doc
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
121 """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
122 entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
123 for name in sorted(items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
124 text = (items[name].__doc__ or '').rstrip()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
125 if not text:
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
126 continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
127 text = gettext(text)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
128 lines = text.splitlines()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
129 lines[1:] = [(' ' + l.strip()) for l in lines[1:]]
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
130 entries.append('\n'.join(lines))
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
131 entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
132 return doc.replace(marker, entries)