[RFC] Documenting plugins

[Ian Clatworthy]

I'm in the process of putting together an updated Plugins Guide that
will include better documentation on some key focus areas, namely:

* Metaprojects (builder, scmproj, externals)
* Patch management (loom, pipeline, rebase)
* Interoperability (bzr-svn, bzr-git, bzr-hg)
* Migration (fastimport, cvsps).
* builddeb.

As part of this exercise, I'd like to put together better guidelines for
Plugin developers so that the contents of
http://doc.bazaar-vcs.org/plugins/en/xxx-plugin.html becomes a
"mini-manual" for each plugin.

Right now, each plugin page has 1 or more subsections:

1. The first subsection is the overview (from __init__.py).
2. Remaining subsections are the help for visible commands
   provided by that plugin (from cmd_xxx docstrings).

I'd like to extend this so that:

3. If a help topic called "xxx-tutorial" exists, it appears second.
4. Other help topics registered by plugins appear after the commands.

So the net effect for something like builddeb
(http://doc.bazaar-vcs.org/plugins/en/builddeb-plugin.html) would be:

1. builddeb - Build Debian packages ... (overview)
2. builddeb-tutorial (NEW)
3. bd-do
4. builddeb
5. import-dsc
6. mark-uploaded
7. merge-package
8. merge-upstream
9. builddeb-tips (NEW)

Likewise, the HOWTO inside the loom plugin would become available as
"bzr help loom-tutorial" and pipeline-vs-loom.txt (in bzr-pipeline)
could be registered as a help topic and it would be included as a
subsection under
http://doc.bazaar-vcs.org/plugins/en/pipeline-plugin.html too.

Any objections?

Ian C.