annotate mercurial/help.py @ 14206:2bf60f158ecb

setdiscovery: limit lines to 80 characters
author Steven Brown <StevenGBrown@gmail.com>
date Thu, 05 May 2011 23:21:37 +0800
parents 135e244776f0
children d5b525697ddb
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
10364
de1e7099d100 dispatch: provide help for disabled extensions and commands
Brodie Rao <me+hg@dackz.net>
parents: 10282
diff changeset
46 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
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 ''
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
50 result = '\n%s\n\n' % header
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
51 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
52 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
53 ':%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
54 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
55
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
56 def extshelp():
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
57 doc = loaddoc('extensions')()
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
58
8871
20a25042fadc extensions: move extensions listing functions from mercurial.help
Cédric Duval <cedricduval@free.fr>
parents: 8865
diff changeset
59 exts, maxlength = extensions.enabled()
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
60 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
61
8871
20a25042fadc extensions: move extensions listing functions from mercurial.help
Cédric Duval <cedricduval@free.fr>
parents: 8865
diff changeset
62 exts, maxlength = extensions.disabled()
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
63 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
64
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
65 return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
66
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
67 def loaddoc(topic):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
68 """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
69
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
70 def loader():
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
71 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
72 module = sys.executable
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
73 else:
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
74 module = __file__
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
75 base = os.path.dirname(module)
7293
3549659450e6 help: add a topic on git diffs (issue1352)
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents: 7013
diff changeset
76
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
77 for dir in ('.', '..'):
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
78 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
79 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
80 break
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
81
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
82 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
83 doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
84 for rewriter in helphooks.get(topic, []):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
85 doc = rewriter(topic, doc)
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
86 return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
87
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
88 return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
89
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
90 helptable = sorted([
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
91 (["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
92 (["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
93 (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
94 (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
95 loaddoc('environment')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
96 (['revs', 'revisions'], _('Specifying Single Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
97 loaddoc('revisions')),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
98 (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
99 loaddoc('multirevs')),
12818
019b8e1e0402 help: add "revset" alias for "revsets" help topic
Martin Geisler <mg@lazybytes.net>
parents: 12771
diff changeset
100 (['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
101 (['diffs'], _('Diff Formats'), loaddoc('diffs')),
12771
c77f6276c9e7 help: help topic for merge tools
Erik Zielke <ez@aragost.com>
parents: 12401
diff changeset
102 (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
103 (['templating', 'templates'], _('Template Usage'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
104 loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
105 (['urls'], _('URL Paths'), loaddoc('urls')),
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
106 (["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
107 (["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
108 (["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
109 (["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
110 (["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
111 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
112 ])
12820
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 # 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
115 # returning the updated version
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
116 helphooks = {
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
117 }
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
118
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
119 def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
120 helphooks.setdefault(topic, []).append(rewriter)
13593
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 def makeitemsdoc(topic, doc, marker, items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
123 """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
124 .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
125 """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
126 entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
127 for name in sorted(items):
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
128 text = (items[name].__doc__ or '').rstrip()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
129 if not text:
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
130 continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
131 text = gettext(text)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
132 lines = text.splitlines()
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
133 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
134 entries.append('\n'.join(lines))
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
135 entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
136 return doc.replace(marker, entries)