Mercurial > public > mercurial-scm > hg

annotate mercurial/help.py @ 13741:b51bf961b3cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
wireproto: add getbundle() function getbundle(common, heads) -> bundle Returns the changegroup for all ancestors of heads which are not ancestors of common. For both sets, the heads are included in the set. Intended to eventually supercede changegroupsubset and changegroup. Uses heads of common region to exclude unwanted changesets instead of bases of desired region, which is more useful and easier to implement. Designed to be extensible with new optional arguments (which will have to be guarded by corresponding capabilities).
author Peter Arrenbrecht <peter.arrenbrecht@gmail.com>
date Wed, 23 Mar 2011 16:02:11 +0100
parents cc4721ed7a2a
children 9e5407a67dea
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
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
11
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 def moduledoc(file):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
14 '''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
15
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
16 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
17 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
18 the synopsis'''
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
19 result = []
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
20
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
21 line = file.readline()
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
22 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
23 line = file.readline()
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
24 if not line:
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
25 break
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
26
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
27 start = line[:3]
12401
4cdaf1adafc8 backout most of 4f8067c94729
Matt Mackall <mpm@selenic.com>
parents: 12387
diff changeset
28 if start == '"""' or start == "'''":
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
29 line = line[3:]
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
30 while line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
31 if line.rstrip().endswith(start):
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
32 line = line.split(start)[0]
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
33 if line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
34 result.append(line)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
35 break
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
36 elif not line:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
37 return None # unmatched delimiter
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
38 result.append(line)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
39 line = file.readline()
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
40 else:
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
41 return None
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
42
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
43 return ''.join(result)
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
44
10364
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
45 def listexts(header, exts, maxlength, indent=1):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
46 '''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
47 if not exts:
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
48 return ''
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
49 result = '\n%s\n\n' % header
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
50 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
51 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
52 ':%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
53 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
54
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
55 def extshelp():
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
56 doc = loaddoc('extensions')()
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
57
8871
20a25042fadc extensions: move extensions listing functions from mercurial.help
C?dric Duval <cedricduval@free.fr>
parents: 8865
diff changeset
58 exts, maxlength = extensions.enabled()
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
59 doc += listexts(_('enabled extensions:'), exts, maxlength)
8864
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
C?dric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
60
8871
20a25042fadc extensions: move extensions listing functions from mercurial.help
C?dric Duval <cedricduval@free.fr>
parents: 8865
diff changeset
61 exts, maxlength = extensions.disabled()
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
62 doc += listexts(_('disabled extensions:'), exts, maxlength)
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
63
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
64 return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
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 loaddoc(topic):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
67 """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
68
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
69 def loader():
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
70 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
71 module = sys.executable
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
72 else:
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
73 module = __file__
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
74 base = os.path.dirname(module)
7293
3549659450e6 help: add a topic on git diffs (issue1352)
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 7013
diff changeset
75
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
76 for dir in ('.', '..'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
77 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
78 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
79 break
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
80
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
81 path = os.path.join(docdir, topic + ".txt")
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
82 doc = gettext(open(path).read())
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
83 for rewriter in helphooks.get(topic, []):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
84 doc = rewriter(topic, doc)
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
85 return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
86
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
87 return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
88
11657
5ed6802e6bcb help: make helptable a list instead of a tuple
Martin Geisler <mg@lazybytes.net>
parents: 11382
diff changeset
89 helptable = [
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
90 (["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
91 (["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
92 (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
93 (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
94 loaddoc('environment')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
95 (['revs', 'revisions'], _('Specifying Single Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
96 loaddoc('revisions')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
97 (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
98 loaddoc('multirevs')),
12818
019b8e1e0402 help: add "revset" alias for "revsets" help topic
Martin Geisler <mg@lazybytes.net>
parents: 12771
diff changeset
99 (['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
100 (['diffs'], _('Diff Formats'), loaddoc('diffs')),
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents: 12401
diff changeset
101 (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
102 (['templating', 'templates'], _('Template Usage'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
103 loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
104 (['urls'], _('URL Paths'), loaddoc('urls')),
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
C?dric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
105 (["extensions"], _("Using additional features"), extshelp),
12828
af1006d2f970 Add subrepos help topic
Patrick Mezard <pmezard@gmail.com>
parents: 12820
diff changeset
106 (["subrepo", "subrepos"], _("Subrepositories"), loaddoc('subrepos')),
10999
38182ed043b7 help: add some help for hgweb.config files
Matt Mackall <mpm@selenic.com>
parents: 10708
diff changeset
107 (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
11356
511445840148 help: add "glossary" topic
Faheem Mitha <faheem@email.unc.edu>
parents: 10999
diff changeset
108 (["glossary"], _("Glossary"), loaddoc('glossary')),
11657
5ed6802e6bcb help: make helptable a list instead of a tuple
Martin Geisler <mg@lazybytes.net>
parents: 11382
diff changeset
109 ]
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
110
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
111 # 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
112 # returning the updated version
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
113 helphooks = {
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
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
116 def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
117 helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
118
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
119 def makeitemsdoc(topic, doc, marker, items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
120 """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
121 .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
122 """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
123 entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
124 for name in sorted(items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
125 text = (items[name].__doc__ or '').rstrip()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
126 if not text:
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
127 continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
128 text = gettext(text)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
129 lines = text.splitlines()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
130 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
131 entries.append('\n'.join(lines))
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
132 entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
133 return doc.replace(marker, entries)