annotate mercurial/help.py @ 12820:0edc0aa7432d stable

help: add topic rewriting hooks They are useful when updating help topics dynamically from extensions.
author Patrick Mezard <pmezard@gmail.com>
date Sat, 23 Oct 2010 19:21:49 +0200
parents 019b8e1e0402
children af1006d2f970
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),
10999
38182ed043b7 help: add some help for hgweb.config files
Matt Mackall <mpm@selenic.com>
parents: 10708
diff changeset
106 (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
11356
511445840148 help: add "glossary" topic
Faheem Mitha <faheem@email.unc.edu>
parents: 10999
diff changeset
107 (["glossary"], _("Glossary"), loaddoc('glossary')),
11657
5ed6802e6bcb help: make helptable a list instead of a tuple
Martin Geisler <mg@lazybytes.net>
parents: 11382
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)