Merge lp:~allenap/commandant/readme-to-rest into lp:commandant
- readme-to-rest
- Merge into trunk
Proposed by
Gavin Panella
Status: | Merged |
---|---|
Approved by: | Jamu Kakar |
Approved revision: | 44 |
Merged at revision: | 43 |
Proposed branch: | lp:~allenap/commandant/readme-to-rest |
Merge into: | lp:commandant |
Diff against target: |
335 lines (+53/-53) 1 file modified
README (+53/-53) |
To merge this branch: | bzr merge lp:~allenap/commandant/readme-to-rest |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Jamu Kakar | Approve | ||
Review via email: mp+109888@code.launchpad.net |
Commit message
Ensure README is valid reST, and renders without warnings.
Description of the change
Fix README so that it's valid reST. I've already uploaded the README in the branch by hand to PyPI and confirmed it works okay there (see http://
To post a comment you must log in.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'README' | |||
2 | --- README 2010-06-12 13:56:44 +0000 | |||
3 | +++ README 2012-06-12 17:11:25 +0000 | |||
4 | @@ -27,18 +27,18 @@ | |||
5 | 27 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. | 27 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |
6 | 28 | 28 | ||
7 | 29 | On Ubuntu systems, the complete text of the GNU General Public | 29 | On Ubuntu systems, the complete text of the GNU General Public |
9 | 30 | Version 2 License is in `/usr/share/common-licenses/GPL-2'. | 30 | Version 2 License is in ``/usr/share/common-licenses/GPL-2``. |
10 | 31 | 31 | ||
11 | 32 | 32 | ||
12 | 33 | Using Commandant | 33 | Using Commandant |
13 | 34 | ================ | 34 | ================ |
14 | 35 | 35 | ||
21 | 36 | Commandant can be used as a command runner. The bin/commandant | 36 | Commandant can be used as a command runner. The ``bin/commandant`` |
22 | 37 | program can present an application made up of commands and help | 37 | program can present an application made up of commands and help topics |
23 | 38 | topics grouped together in a directory. The 'example' program | 38 | grouped together in a directory. The ``example`` program described in |
24 | 39 | described in the following sections is available in the | 39 | the following sections is available in the ``example`` directory. You |
25 | 40 | extras/example directory. You can try it out from the current | 40 | can try it out from the current directory by running the following |
26 | 41 | directory by running the following commands. | 41 | commands:: |
27 | 42 | 42 | ||
28 | 43 | $ alias example="bin/commandant example" | 43 | $ alias example="bin/commandant example" |
29 | 44 | $ source example/tab-completion.sh | 44 | $ source example/tab-completion.sh |
30 | @@ -48,12 +48,12 @@ | |||
31 | 48 | --------------------------- | 48 | --------------------------- |
32 | 49 | 49 | ||
33 | 50 | Commands are grouped into Commandant programs. A Commandant program | 50 | Commands are grouped into Commandant programs. A Commandant program |
35 | 51 | is made up of an arbitrary number of commands stored in a directory. | 51 | is made up of an arbitrary number of commands stored in a directory:: |
36 | 52 | 52 | ||
37 | 53 | $ mkdir -p ~/example | 53 | $ mkdir -p ~/example |
38 | 54 | 54 | ||
39 | 55 | An alias can be used to provide a name that can used to run commands | 55 | An alias can be used to provide a name that can used to run commands |
41 | 56 | in the Commandant program. | 56 | in the Commandant program:: |
42 | 57 | 57 | ||
43 | 58 | $ alias example="commandant ~/example" | 58 | $ alias example="commandant ~/example" |
44 | 59 | 59 | ||
45 | @@ -61,8 +61,8 @@ | |||
46 | 61 | Getting help | 61 | Getting help |
47 | 62 | ------------ | 62 | ------------ |
48 | 63 | 63 | ||
51 | 64 | Commands provides builtin 'help' and 'version' commands. Running | 64 | Commands provides builtin ``help`` and ``version`` commands. Running |
52 | 65 | the example program by itself shows basic help information. | 65 | the example program by itself shows basic help information:: |
53 | 66 | 66 | ||
54 | 67 | $ example | 67 | $ example |
55 | 68 | Commandant -- a framework for building command-oriented tools | 68 | Commandant -- a framework for building command-oriented tools |
56 | @@ -72,21 +72,21 @@ | |||
57 | 72 | commandant help commands List all commands | 72 | commandant help commands List all commands |
58 | 73 | commandant help topics List all help topics | 73 | commandant help topics List all help topics |
59 | 74 | 74 | ||
62 | 75 | Passing the 'commands' topic to the 'help' command lists the | 75 | Passing the ``commands`` topic to the ``help`` command lists the |
63 | 76 | commands that are available, with a short summary about each one. | 76 | commands that are available, with a short summary about each one:: |
64 | 77 | 77 | ||
65 | 78 | $ example help commands | 78 | $ example help commands |
66 | 79 | help Show help about a command or topic. | 79 | help Show help about a command or topic. |
67 | 80 | version Show version of commandant. | 80 | version Show version of commandant. |
68 | 81 | 81 | ||
71 | 82 | Passing the 'topics' topic to the 'help' command lists the help | 82 | Passing the ``topics`` topic to the ``help`` command lists the help |
72 | 83 | topics that are available, with a short summary about each one. | 83 | topics that are available, with a short summary about each one:: |
73 | 84 | 84 | ||
74 | 85 | $ example help topics | 85 | $ example help topics |
75 | 86 | commands Basic help for all commands. | 86 | commands Basic help for all commands. |
76 | 87 | topics Topics list. | 87 | topics Topics list. |
77 | 88 | 88 | ||
79 | 89 | The 'version' command shows the version of Commandant being used. | 89 | The ``version`` command shows the version of Commandant being used:: |
80 | 90 | 90 | ||
81 | 91 | $ example version | 91 | $ example version |
82 | 92 | commandant 0.1 | 92 | commandant 0.1 |
83 | @@ -96,13 +96,13 @@ | |||
84 | 96 | ---------------------------- | 96 | ---------------------------- |
85 | 97 | 97 | ||
86 | 98 | One of the easiest ways to add a command to a Commandant program is | 98 | One of the easiest ways to add a command to a Commandant program is |
88 | 99 | by creating a shell script and making it executable. | 99 | by creating a shell script and making it executable:: |
89 | 100 | 100 | ||
90 | 101 | $ echo -e '#!/bin/sh\necho Hello, world!' > ~/example/hello | 101 | $ echo -e '#!/bin/sh\necho Hello, world!' > ~/example/hello |
91 | 102 | $ chmod +x ~/example/hello | 102 | $ chmod +x ~/example/hello |
92 | 103 | 103 | ||
95 | 104 | The new 'hello' command in the 'example' program is now registered | 104 | The new ``hello`` command in the ``example`` program is now registered |
96 | 105 | and ready to use. | 105 | and ready to use:: |
97 | 106 | 106 | ||
98 | 107 | $ example help commands | 107 | $ example help commands |
99 | 108 | hello | 108 | hello |
100 | @@ -110,7 +110,7 @@ | |||
101 | 110 | version Show version of commandant. | 110 | version Show version of commandant. |
102 | 111 | 111 | ||
103 | 112 | You should see 'Hello, world!' printed to your screen when you run | 112 | You should see 'Hello, world!' printed to your screen when you run |
105 | 113 | it. | 113 | it:: |
106 | 114 | 114 | ||
107 | 115 | $ example hello | 115 | $ example hello |
108 | 116 | Hello, world! | 116 | Hello, world! |
109 | @@ -120,13 +120,13 @@ | |||
110 | 120 | ------------------------------------------------- | 120 | ------------------------------------------------- |
111 | 121 | 121 | ||
112 | 122 | Commandant will pass all arguments beyond the command name to the | 122 | Commandant will pass all arguments beyond the command name to the |
114 | 123 | executable for that command. | 123 | executable for that command:: |
115 | 124 | 124 | ||
116 | 125 | $ echo -e '#!/bin/sh\necho $*' > ~/example/echo | 125 | $ echo -e '#!/bin/sh\necho $*' > ~/example/echo |
117 | 126 | $ chmod +x ~/example/echo | 126 | $ chmod +x ~/example/echo |
118 | 127 | 127 | ||
119 | 128 | Again, just by putting an executable file in the command directory, | 128 | Again, just by putting an executable file in the command directory, |
121 | 129 | the new 'echo' command has been added to the 'example' program. | 129 | the new ``echo`` command has been added to the ``example`` program:: |
122 | 130 | 130 | ||
123 | 131 | $ example help commands | 131 | $ example help commands |
124 | 132 | echo | 132 | echo |
125 | @@ -134,7 +134,7 @@ | |||
126 | 134 | help Show help about a command or topic. | 134 | help Show help about a command or topic. |
127 | 135 | version Show version of commandant. | 135 | version Show version of commandant. |
128 | 136 | 136 | ||
130 | 137 | The new 'echo' command will repeat whatever we tell it. | 137 | The new ``echo`` command will repeat whatever we tell it:: |
131 | 138 | 138 | ||
132 | 139 | $ example echo Hello there! | 139 | $ example echo Hello there! |
133 | 140 | Hello there! | 140 | Hello there! |
134 | @@ -143,12 +143,12 @@ | |||
135 | 143 | Providing help for commands | 143 | Providing help for commands |
136 | 144 | --------------------------- | 144 | --------------------------- |
137 | 145 | 145 | ||
139 | 146 | The commands in the 'example' program have been very easy to add, | 146 | The commands in the ``example`` program have been very easy to add, |
140 | 147 | but they could be easier to use. Commandant's builtin help system | 147 | but they could be easier to use. Commandant's builtin help system |
141 | 148 | can be extended to provide help topics for user-provided commands. | 148 | can be extended to provide help topics for user-provided commands. |
142 | 149 | Files in the command directory with a .txt extension, and with the | 149 | Files in the command directory with a .txt extension, and with the |
143 | 150 | same name as a command, will be treated as help content for that | 150 | same name as a command, will be treated as help content for that |
145 | 151 | command. Adding help content for the 'hello' command is quite easy. | 151 | command. Adding help content for the ``hello`` command is quite easy:: |
146 | 152 | 152 | ||
147 | 153 | $ cat ~/example/hello.txt | 153 | $ cat ~/example/hello.txt |
148 | 154 | Greet the world! | 154 | Greet the world! |
149 | @@ -156,7 +156,7 @@ | |||
150 | 156 | Print 'Hello, world!' to the screen. | 156 | Print 'Hello, world!' to the screen. |
151 | 157 | 157 | ||
152 | 158 | The first line in a help topic is used as a short description. This | 158 | The first line in a help topic is used as a short description. This |
154 | 159 | short description is used when listing commands. | 159 | short description is used when listing commands:: |
155 | 160 | 160 | ||
156 | 161 | $ example help commands | 161 | $ example help commands |
157 | 162 | echo | 162 | echo |
158 | @@ -164,9 +164,9 @@ | |||
159 | 164 | help Show help about a command or topic. | 164 | help Show help about a command or topic. |
160 | 165 | version Show version of commandant. | 165 | version Show version of commandant. |
161 | 166 | 166 | ||
163 | 167 | Notice that the 'hello' command uses the short description from the | 167 | Notice that the ``hello`` command uses the short description from the |
164 | 168 | help topic. The complete help text can be seen by passing the | 168 | help topic. The complete help text can be seen by passing the |
166 | 169 | command name to the 'help' command. | 169 | command name to the ``help`` command:: |
167 | 170 | 170 | ||
168 | 171 | $ example help hello | 171 | $ example help hello |
169 | 172 | Print 'Hello, world!' to the screen. | 172 | Print 'Hello, world!' to the screen. |
170 | @@ -175,9 +175,9 @@ | |||
171 | 175 | Providing a custom splash page | 175 | Providing a custom splash page |
172 | 176 | ------------------------------ | 176 | ------------------------------ |
173 | 177 | 177 | ||
175 | 178 | The stock help text shown when the 'help' command is run points | 178 | The stock help text shown when the ``help`` command is run points |
176 | 179 | users to the list of commands and help topics. It can be overridden | 179 | users to the list of commands and help topics. It can be overridden |
178 | 180 | by providing a file called basic.txt. | 180 | by providing a file called basic.txt:: |
179 | 181 | 181 | ||
180 | 182 | $ cat ~/example/basic.txt | 182 | $ cat ~/example/basic.txt |
181 | 183 | example -- A collection of command examples that work with Commandant. | 183 | example -- A collection of command examples that work with Commandant. |
182 | @@ -187,8 +187,8 @@ | |||
183 | 187 | example help commands List all commands | 187 | example help commands List all commands |
184 | 188 | example help topics List all help topics | 188 | example help topics List all help topics |
185 | 189 | 189 | ||
188 | 190 | The contents of this file are shown when the 'help' command is run | 190 | The contents of this file are shown when the ``help`` command is run |
189 | 191 | without a topic. | 191 | without a topic:: |
190 | 192 | 192 | ||
191 | 193 | $ example help | 193 | $ example help |
192 | 194 | example -- A collection of command examples that work with Commandant. | 194 | example -- A collection of command examples that work with Commandant. |
193 | @@ -206,7 +206,7 @@ | |||
194 | 206 | topics, not bound to any command name. Files in the command | 206 | topics, not bound to any command name. Files in the command |
195 | 207 | directory with a .txt extension, and with a name that doesn't match | 207 | directory with a .txt extension, and with a name that doesn't match |
196 | 208 | any command name, will be treated as help topics. Adding help to | 208 | any command name, will be treated as help topics. Adding help to |
198 | 209 | describe a concept, for example, is quite easy. | 209 | describe a concept, for example, is quite easy:: |
199 | 210 | 210 | ||
200 | 211 | $ cat ~/example/greetings.txt | 211 | $ cat ~/example/greetings.txt |
201 | 212 | Greetings are a way to initiate communication. | 212 | Greetings are a way to initiate communication. |
202 | @@ -221,15 +221,15 @@ | |||
203 | 221 | 221 | ||
204 | 222 | As with help files for commands, the first line contains a short | 222 | As with help files for commands, the first line contains a short |
205 | 223 | summary with help text following. The topic will now appear in the | 223 | summary with help text following. The topic will now appear in the |
207 | 224 | topics list. | 224 | topics list:: |
208 | 225 | 225 | ||
209 | 226 | $ example help topics | 226 | $ example help topics |
210 | 227 | commands Basic help for all commands. | 227 | commands Basic help for all commands. |
211 | 228 | greetings Greetings are a way to initiate communication. | 228 | greetings Greetings are a way to initiate communication. |
212 | 229 | topics Topics list. | 229 | topics Topics list. |
213 | 230 | 230 | ||
216 | 231 | The help text can be seen by passing the topic name to the 'help' | 231 | The help text can be seen by passing the topic name to the ``help`` |
217 | 232 | command. | 232 | command:: |
218 | 233 | 233 | ||
219 | 234 | $ example help greetings | 234 | $ example help greetings |
220 | 235 | Greeting (also called accosting) is a way for human beings (as well | 235 | Greeting (also called accosting) is a way for human beings (as well |
221 | @@ -252,7 +252,7 @@ | |||
222 | 252 | Commandant loads commands from the command directory it imports | 252 | Commandant loads commands from the command directory it imports |
223 | 253 | Python commands from files with a .py extension. The commands in | 253 | Python commands from files with a .py extension. The commands in |
224 | 254 | the files need to subclass the Command class and need to be named | 254 | the files need to subclass the Command class and need to be named |
226 | 255 | using the cmd_<name> naming convention. | 255 | using the cmd_<name> naming convention:: |
227 | 256 | 256 | ||
228 | 257 | $ cat example/rock-fact.py | 257 | $ cat example/rock-fact.py |
229 | 258 | from bzrlib.commands import Command | 258 | from bzrlib.commands import Command |
230 | @@ -266,9 +266,9 @@ | |||
231 | 266 | print >>self.outf, "Rocks are really hard." | 266 | print >>self.outf, "Rocks are really hard." |
232 | 267 | 267 | ||
233 | 268 | Just like with executable commands, adding a Python command is as | 268 | Just like with executable commands, adding a Python command is as |
235 | 269 | easy as adding a file to the command directory. An 'outf' attribute | 269 | easy as adding a file to the command directory. An ``outf`` attribute |
236 | 270 | will be set on the command object when it's run and should be used | 270 | will be set on the command object when it's run and should be used |
238 | 271 | when printing text. | 271 | when printing text:: |
239 | 272 | 272 | ||
240 | 273 | $ example help commands | 273 | $ example help commands |
241 | 274 | echo | 274 | echo |
242 | @@ -278,10 +278,10 @@ | |||
243 | 278 | version Show version of commandant. | 278 | version Show version of commandant. |
244 | 279 | 279 | ||
245 | 280 | The new command is available using the name of the class, without | 280 | The new command is available using the name of the class, without |
247 | 281 | the 'cmd_' part, and with underscores converted to dashes. The | 281 | the ``cmd_`` part, and with underscores converted to dashes. The |
248 | 282 | doctring is used to provide builtin help. The first line is used as | 282 | doctring is used to provide builtin help. The first line is used as |
249 | 283 | the summary and the subsequent content is used as the help text, | 283 | the summary and the subsequent content is used as the help text, |
251 | 284 | just like in help files for executable commands. | 284 | just like in help files for executable commands:: |
252 | 285 | 285 | ||
253 | 286 | $ example help rock-fact | 286 | $ example help rock-fact |
254 | 287 | This command prints a fascinating fact about rocks. | 287 | This command prints a fascinating fact about rocks. |
255 | @@ -296,7 +296,7 @@ | |||
256 | 296 | One of the main advantages of writing Python commands is being able | 296 | One of the main advantages of writing Python commands is being able |
257 | 297 | to express command-line argument and option parameters. bzrlib uses | 297 | to express command-line argument and option parameters. bzrlib uses |
258 | 298 | this data to automatically provide parsing and integration with the | 298 | this data to automatically provide parsing and integration with the |
260 | 299 | help system. | 299 | help system:: |
261 | 300 | 300 | ||
262 | 301 | $ cat example/fortune.py | 301 | $ cat example/fortune.py |
263 | 302 | from random import randint | 302 | from random import randint |
264 | @@ -335,7 +335,7 @@ | |||
265 | 335 | Commandant has builtin support for writing commands that need to run | 335 | Commandant has builtin support for writing commands that need to run |
266 | 336 | in a Twisted reactor. Simply subclass TwistedCommand and implement | 336 | in a Twisted reactor. Simply subclass TwistedCommand and implement |
267 | 337 | a command as you normally would. It's run() method will be called | 337 | a command as you normally would. It's run() method will be called |
269 | 338 | inside a running reactor. | 338 | inside a running reactor:: |
270 | 339 | 339 | ||
271 | 340 | $ cat example/get-page.py | 340 | $ cat example/get-page.py |
272 | 341 | from twisted.internet import reactor | 341 | from twisted.internet import reactor |
273 | @@ -390,7 +390,7 @@ | |||
274 | 390 | 390 | ||
275 | 391 | The first step is to create an entry point which registers commands | 391 | The first step is to create an entry point which registers commands |
276 | 392 | and help topics and then subsequently runs your program. The | 392 | and help topics and then subsequently runs your program. The |
278 | 393 | CommandController is both a registry and dispatching device: | 393 | CommandController is both a registry and dispatching device:: |
279 | 394 | 394 | ||
280 | 395 | from commandant import builtins | 395 | from commandant import builtins |
281 | 396 | from commandant.controller import CommandController | 396 | from commandant.controller import CommandController |
282 | @@ -413,9 +413,9 @@ | |||
283 | 413 | controller.run(argv[1:]) | 413 | controller.run(argv[1:]) |
284 | 414 | 414 | ||
285 | 415 | The name, version, summary and URL are used in generated help text. | 415 | The name, version, summary and URL are used in generated help text. |
289 | 416 | The 'builtins' module contains the builtin 'help' and 'version' | 416 | The ``builtins`` module contains the builtin ``help`` and ``version`` |
290 | 417 | commands, and the 'basic', 'commands', 'hidden-commands' and | 417 | commands, and the ``basic``, ``commands``, ``hidden-commands`` and |
291 | 418 | 'topics' help topics. | 418 | ``topics`` help topics. |
292 | 419 | 419 | ||
293 | 420 | 420 | ||
294 | 421 | Registering application commands | 421 | Registering application commands |
295 | @@ -423,10 +423,10 @@ | |||
296 | 423 | 423 | ||
297 | 424 | Commands can be grouped in a module and registered with the command | 424 | Commands can be grouped in a module and registered with the command |
298 | 425 | controller. Just like in the examples above, command classes should | 425 | controller. Just like in the examples above, command classes should |
300 | 426 | be named using the 'cmd_command_name' naming convention and will be | 426 | be named using the ``cmd_command_name`` naming convention and will be |
301 | 427 | loaded automatically when the module is registered. If all the | 427 | loaded automatically when the module is registered. If all the |
302 | 428 | commands in the examples above were grouped in an example.commands | 428 | commands in the examples above were grouped in an example.commands |
304 | 429 | module they could be registered just like the builtin commands: | 429 | module they could be registered just like the builtin commands:: |
305 | 430 | 430 | ||
306 | 431 | from example import commands | 431 | from example import commands |
307 | 432 | 432 | ||
308 | @@ -438,7 +438,7 @@ | |||
309 | 438 | 438 | ||
310 | 439 | In the examples above, help topics are text files in a directory. | 439 | In the examples above, help topics are text files in a directory. |
311 | 440 | When embedding Commandant in an application, its easier to use | 440 | When embedding Commandant in an application, its easier to use |
313 | 441 | Python for help topics: | 441 | Python for help topics:: |
314 | 442 | 442 | ||
315 | 443 | from commandant.help_topics import DocstringHelpTopic | 443 | from commandant.help_topics import DocstringHelpTopic |
316 | 444 | 444 | ||
317 | @@ -456,7 +456,7 @@ | |||
318 | 456 | 456 | ||
319 | 457 | Registering help topics is just like registering commands. They can | 457 | Registering help topics is just like registering commands. They can |
320 | 458 | be grouped in a module and registered with the command controller. | 458 | be grouped in a module and registered with the command controller. |
322 | 459 | Topics should use the 'topic_document_name' naming convention. | 459 | Topics should use the ``topic_document_name`` naming convention:: |
323 | 460 | 460 | ||
324 | 461 | from example import help_topics | 461 | from example import help_topics |
325 | 462 | 462 | ||
326 | @@ -466,7 +466,7 @@ | |||
327 | 466 | Providing a custom splash page | 466 | Providing a custom splash page |
328 | 467 | ------------------------------ | 467 | ------------------------------ |
329 | 468 | 468 | ||
331 | 469 | The stock help text shown when the 'help' command is run points | 469 | The stock help text shown when the ``help`` command is run points |
332 | 470 | users to the list of commands and help topics that have been | 470 | users to the list of commands and help topics that have been |
334 | 471 | registered with the controller. If a 'topic_basic' help topic has | 471 | registered with the controller. If a ``topic_basic`` help topic has |
335 | 472 | been registered it will be shown instead of the builtin splash page. | 472 | been registered it will be shown instead of the builtin splash page. |
This is great, thanks!