Updated Plugins Guide - questions and RFT

[Neil Martinsen-Burrell]

On 2009-09-23 19:57 , Ian Clatworthy wrote:
> Neil Martinsen-Burrell wrote:
>
>> One problem with the css from Sphinx is apparently that code blocks as
>> one gets with the double-colon don't have a distinct style.  See
>> http://doc.bazaar-vcs.org/plugins/en/automirror-plugin.html where the
>> line starting "echo..." is a preformatted block.
>
> Add a space (or two) before echo and the formatting will work. The doc
> for many plugins needs this done.

Thanks, good eye.

>> I've updated bzr-automirror according to your suggestions.  I feel as if
>> I'm duplicating a great deal of content between README.txt and
>> __init__.py.  As a plugin author yourself, do you have any suggestion on
>> how to manage the problem?
>
> I put the information in __init__.py and tell them in the README to run
>
>    bzr help xxx
>
> E.g.
>
>    bzr help autommirror
>
> As long as the plugin name doesn't exactly match a command name, that
> will work. If it does clash, then you need
>
>    bzr help plugins/xxx
>
> instead. You can also reference the Guide's HTML page for your plugin in
> your README. The URLs should be stable and readable.

I took the path of renaming README.txt to INSTALL.txt and trimming it 
down to only include installation instructions and a pointer to ``bzr 
help automirror``.  My thinking was that installing the plugin is the 
only thing that can't be documented from within Bazaar.  Then, the 
installation instructions are the only content duplicated between the 
docstring and a separate file.  (They are nice to have in the docstring 
so that they appear in the Plugins Guide.)

-Neil