← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

  • Committer: Robert Collins
  • Date: 2005-10-18 13:11:57 UTC
  • mfrom: (1185.16.72) (0.2.1)
  • Revision ID: robertc@robertcollins.net-20051018131157-76a9970aa78e927e
Merged Martin.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics.py
1
 
# Copyright (C) 2006 Canonical Ltd
2
 
#
3
 
# This program is free software; you can redistribute it and/or modify
4
 
# it under the terms of the GNU General Public License as published by
5
 
# the Free Software Foundation; either version 2 of the License, or
6
 
# (at your option) any later version.
7
 
#
8
 
# This program is distributed in the hope that it will be useful,
9
 
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
 
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
 
# GNU General Public License for more details.
12
 
#
13
 
# You should have received a copy of the GNU General Public License
14
 
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
17
 
"""A collection of extra help information for using bzr.
18
 
 
19
 
Help topics are meant to be help for items that aren't commands, but will
20
 
help bzr become fully learnable without referring to a tutorial.
21
 
"""
22
 
 
23
 
from bzrlib import registry
24
 
 
25
 
 
26
 
class HelpTopicRegistry(registry.Registry):
27
 
    """A Registry customized for handling help topics."""
28
 
 
29
 
    def register(self, topic, detail, summary):
30
 
        """Register a new help topic.
31
 
 
32
 
        :param topic: Name of documentation entry
33
 
        :param detail: Function or string object providing detailed
34
 
            documentation for topic.  Function interface is detail(topic).
35
 
            This should return a text string of the detailed information.
36
 
        :param summary: String providing single-line documentation for topic.
37
 
        """
38
 
        # The detail is stored as the 'object' and the 
39
 
        super(HelpTopicRegistry, self).register(topic, detail, info=summary)
40
 
 
41
 
    def register_lazy(self, topic, module_name, member_name, summary):
42
 
        """Register a new help topic, and import the details on demand.
43
 
 
44
 
        :param topic: Name of documentation entry
45
 
        :param module_name: The module to find the detailed help.
46
 
        :param member_name: The member of the module to use for detailed help.
47
 
        :param summary: String providing single-line documentation for topic.
48
 
        """
49
 
        super(HelpTopicRegistry, self).register_lazy(topic, module_name,
50
 
                                                     member_name, info=summary)
51
 
 
52
 
    def get_detail(self, topic):
53
 
        """Get the detailed help on a given topic."""
54
 
        obj = self.get(topic)
55
 
        if callable(obj):
56
 
            return obj(topic)
57
 
        else:
58
 
            return obj
59
 
 
60
 
    def get_summary(self, topic):
61
 
        """Get the single line summary for the topic."""
62
 
        return self.get_info(topic)
63
 
 
64
 
 
65
 
topic_registry = HelpTopicRegistry()
66
 
 
67
 
 
68
 
#----------------------------------------------------
69
 
 
70
 
def _help_on_topics(dummy):
71
 
    """Write out the help for topics to outfile"""
72
 
 
73
 
    topics = topic_registry.keys()
74
 
    lmax = max(len(topic) for topic in topics)
75
 
        
76
 
    out = []
77
 
    for topic in topics:
78
 
        summary = topic_registry.get_summary(topic)
79
 
        out.append("%-*s %s\n" % (lmax, topic, summary))
80
 
    return ''.join(out)
81
 
 
82
 
 
83
 
def _help_on_revisionspec(name):
84
 
    """"Write the summary help for all documented topics to outfile."""
85
 
    import bzrlib.revisionspec
86
 
 
87
 
    out = []
88
 
    out.append("\nRevision prefix specifier:"
89
 
               "\n--------------------------\n")
90
 
 
91
 
    for i in bzrlib.revisionspec.SPEC_TYPES:
92
 
        doc = i.help_txt
93
 
        if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
94
 
            doc = "N/A\n"
95
 
        while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
96
 
            doc = doc[:-1]
97
 
 
98
 
        out.append("  %s %s\n\n" % (i.prefix, doc))
99
 
 
100
 
    return ''.join(out)
101
 
 
102
 
 
103
 
_basic_help= \
104
 
"""Bazaar -- a free distributed version-control tool
105
 
http://bazaar-vcs.org/
106
 
 
107
 
Basic commands:
108
 
  bzr init           makes this directory a versioned branch
109
 
  bzr branch         make a copy of another branch
110
 
 
111
 
  bzr add            make files or directories versioned
112
 
  bzr ignore         ignore a file or pattern
113
 
  bzr mv             move or rename a versioned file
114
 
 
115
 
  bzr status         summarize changes in working copy
116
 
  bzr diff           show detailed diffs
117
 
 
118
 
  bzr merge          pull in changes from another branch
119
 
  bzr commit         save some or all changes
120
 
 
121
 
  bzr log            show history of changes
122
 
  bzr check          validate storage
123
 
 
124
 
  bzr help init      more help on e.g. init command
125
 
  bzr help commands  list all commands
126
 
  bzr help topics    list all help topics
127
 
"""
128
 
 
129
 
 
130
 
_global_options =\
131
 
"""Global Options
132
 
 
133
 
These options may be used with any command, and may appear in front of any
134
 
command.  (e.g. "bzr --quiet help").
135
 
 
136
 
--quiet        Suppress informational output; only print errors and warnings
137
 
--version      Print the version number
138
 
 
139
 
--no-aliases   Do not process command aliases when running this command
140
 
--builtin      Use the built-in version of a command, not the plugin version.
141
 
               This does not suppress other plugin effects
142
 
--no-plugins   Do not process any plugins
143
 
 
144
 
-Derror        Instead of normal error handling, always print a traceback on
145
 
               error.
146
 
--profile      Profile execution using the hotshot profiler
147
 
--lsprof       Profile execution using the lsprof profiler
148
 
--lsprof-file  Profile execution using the lsprof profiler, and write the
149
 
               results to a specified file.
150
 
 
151
 
Note: --version must be supplied before any command.
152
 
"""
153
 
 
154
 
 
155
 
topic_registry.register("revisionspec", _help_on_revisionspec,
156
 
                        "Explain how to use --revision")
157
 
topic_registry.register('basic', _basic_help, "Basic commands")
158
 
topic_registry.register('topics', _help_on_topics, "Topics list")
159
 
def get_format_topic(topic):
160
 
    from bzrlib import bzrdir
161
 
    return bzrdir.format_registry.help_topic(topic)
162
 
topic_registry.register('formats', get_format_topic, 'Directory formats')
163
 
topic_registry.register('global-options', _global_options,
164
 
                        'Options that can be used with any command')