Merge lp:~jelmer/brz/yet-more-docs into lp:brz

[Jelmer Vernooij]

Some more minor improvements to the docs.

Some more minor improvements to the docs:

 * Fix links to glossary and developer docs
 * Drop canonical-specific blurb from Launchpad tutorial

[Martin Packman (gz)]

Thanks! Am aware this is mostly ported over text, but have left some inline comments for things that seem not quite right.

review: Approve

=== modified file 'doc/developers/index-plain.txt'
--- doc/developers/index-plain.txt	2018-11-18 14:23:08 +0000
+++ doc/developers/index-plain.txt	2018-11-22 02:24:44 +0000
@@ -28,8 +28,8 @@
 
 * `Breezy Code Style Guide <code-style.html>`_.
 
-* `Writing plugins <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_
-  |--| specific advice on writing Breezy plugins. (web link)
+* `Writing plugins <plugin-development.html>`_
+  |--| specific advice on writing Breezy plugins.
 
 * `Documenting changes <documenting-changes.html>`_.
 
 
=== modified file 'doc/developers/index.txt'
--- doc/developers/index.txt	2018-11-18 14:23:08 +0000
+++ doc/developers/index.txt	2018-11-22 02:24:44 +0000
@@ -60,7 +60,7 @@
    overview
    integration
 
-* `Writing plugins for Breezy <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ (web link)
+* `Writing plugins for Breezy <plugin-development.txt>`_
 
 * `breezy API reference <api/index.txt>`_
 
 
=== modified file 'doc/developers/plugin-api.txt'
--- doc/developers/plugin-api.txt	2018-11-18 18:23:32 +0000
+++ doc/developers/plugin-api.txt	2018-11-22 02:24:44 +0000
@@ -23,7 +23,7 @@
 --------
 
  * `Breezy Developer Documentation Catalog <../index.html>`_.
- * `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for
+ * `Breezy Plugins Guide <plugin-development.txt>`_ for
    more suggestions about particular APIs.
 
 
@@ -241,7 +241,7 @@
 time other than register or override functions to be called later.
 
 The plugin can import breezy and call any function.
-Some interesting APIs are described in `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_.
+Some interesting APIs are described in `Breezy Plugins Guide <plugin-development.txt>`_.
 
 
 Publishing your plugin
 
=== added file 'doc/developers/plugin-development.txt'
--- doc/developers/plugin-development.txt	1970-01-01 00:00:00 +0000
+++ doc/developers/plugin-development.txt	2018-11-22 02:24:44 +0000
@@ -0,0 +1,264 @@
+Developing a plugin
+===================
+
+Naming
+------
+
+By convention, most plugins are named brz-xxx and are installed into a
+directory called xxx. Note that the directory name must be a legal
+Python package name, so a plugin called brz-xxx-yyy need to be installed
+into a directory called xxx_yyy, i.e. '-' in a plugin name should be mapped to
+an underscore in the directory name.
+
+
+Licensing
+---------
+
+We encourage plugin authors to make their plugins publicly available
+under the same license as Breezy itself, namely GPL v2 or later. However, there
+is no requirement to do so. You are free to create Breezy plugins for
+private or internal use within your company and not distribute them.
+
+By sharing your work, a larger number of people benefit. In our experience,
+plugin developers also benefit heavily by having more users involved in
+the design, testing, bug fixing and longer term maintenance. In other words,
+sharing leads to a better plugin faster.
+
+
+Testing
+-------
+
+To ensure your plugin under development is available to Breezy, set
+the ``BRZ_PLUGIN_PATH`` environment variable to its parent directory.
+Alternatively, you may wish to develop your plugin within a directory
+under your personal plugins area (``~/.bazaar/plugins`` on GNU/Linux)
+or put a symbolic link in that area pointing to your plugin under
+test.  Finally you can use ``BRZ_PLUGINS_AT`` to point to a specific
+directory for a specific plugin (separated by your platform's value of
+os.pathsep), e.g.
+
+  export BRZ_PLUGINS_AT=qbrz@/home/me/qbrz:explorer@/home/me/explorer
+
+You can disable loading plugins with ``BRZ_DISABLE_PLUGINS``.
+
+If you want to stop loading all but installed plugins you can use:
+
+  BRZ_PLUGIN_PATH=-site
+
+We also encourage plugin developers to provide tests for their plugin.
+When you run ``brz selftest``, Breezy will scan all its plugins to see if
+they contain a function named ``test_suite()``.  For each plugin that does,
+it calls the function and adds any resulting tests to the master test suite.
+To run just the tests for plugin xxx, the command is::
+
+  brz selftest -s bp.xxx
+
+
+Providing help
+--------------
+
+Plugins in this guide have their documentation automatically
+generated from the online help provided for a plugin. Sections are
+ordered as follows:
+
+1. High level introduction
+2. Plugin-specific help topics (COMING SOON)
+3. Commands defined or extended by the plugin.
+
+High level help is specified in the docstring for the ``__init__.py`` module.
+You can register plugin-specific help topics in ``__init__.py`` like this::
+
+  _xxx_tutorial = """XXX Tutorial
+
+  Welcome to xxx, your new best friend. ...
+  """
+  topic_registry.register('xxx-tutorial',
+      _xxx_tutorial,
+      'How to use xxx')
+
+Command level help is specified in the docstring for the relevant 
+``cmd_xxx`` Command class.
+
+.. note::
+
+   The final documentation needs to be in ReST format. Keep in mind though
+   that the documentation should also be readable via ``brz help xxx`` so
+   it's best to keep markup to a reasonable minimum.
+   
+
+Providing custom code via hooks
+-------------------------------
+
+Hooks let you provide custom code at certain processing points.
+The available hook point are documented in the `User Reference
+<http://doc.bazaar-vcs.org/development/en/user-reference/index.html#hooks>`_.
+
+Adding a new hook is done with, for example::
+
+  import breezy.branch
+  breezy.branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
+                                 'My post_push hook')
+
+For more information on how to write hooks,
+see http://doc.bazaar-vcs.org/development/en/user-guide/hooks.html.
+
+
+Defining a new command
+----------------------
+
+Breezy commands are defined as subclasses of ``breezy.commands.Command``, the
+command name is specified by the name of the subclass, and they must be
+registered into ``brz`` with the ``breezy.commands.register_command`` function
+at module import time.
+
+To define the ``brz foo-bar`` command::
+
+  from breezy.commands import Command, register_command
+
+  class cmd_foo_bar(Command):
+    # see breezy/builtins.py for information about what to put here
+    pass
+
+  register_command(cmd_foo_bar)
+
+If the class name starts with ``cmd_``, the prefix will get dropped
+and ``_`` will be replaced by ``-`` characters.
+
+
+Managing data
+-------------
+
+Plugin data falls into several categories:
+
+* Configuration settings.
+* Data the user can see and version control.
+* Data behind the scenes.
+
+Configuration settings are often stored in ``branch.conf``,
+``locations.conf`` or ``bazaar.conf``.
+
+User-visible data for a plugin called xxx should be stored in
+``.bzrmeta/xxx``. If mutiple files are desirable, make ``.bzrmeta/xxx``
+a directory or give them a common prefix within ``.bzrmeta``, e.g.
+``xxx-foo``, ``xxx-bar``.
+
+Data managed behind the scenes should be stored in ``.bzr``.
+Depending on the nature of the data, it may belong in a subdirectory
+within there, e.g. ``checkout``, ``branch`` or ``repository``.
+It's your responsibility to ensure behind-the-scenes data is
+propagated and merged appropriately via custom code. You may want
+to use existing hooks for this or ask for new hooks to help.
+
+Useful metadata
+---------------
+
+It is highly recommended that plugins define a version number. This
+is displayed by ``brz plugins`` and by the ``qplugins`` GUI dialog.
+To do this, define ``version_info`` in ``__init__.py`` like this::
+
+  version_info = (1, 2, 0, 'beta', 1)
+
+Plugins can also declare other useful metadata such as a mimimum
+breezy version, new transports and storage formats. See
+`Plugin API <plugin-api>`_ for details.
+
+
+Performance tips
+----------------
+
+When brz starts up, it imports every plugin, so plugins can degrade
+performance when they're not being used. However, sub-modules are not
+loaded, only the main name.
+
+One way you can avoid this slowdown is by putting most of your code
+in sub-modules, so that the plugin, itself, is small. All you really
+need in the ``__init__.py`` is the plugin's Command classes, the
+commands to register them, and the optional ``test_suite()``.
+
+Another way to reduce your plugin's overhead is to use the breezy
+lazy_import functionality. That looks something like this::
+
+  from breezy.lazy_import import lazy_import
+  lazy_import(globals(), """
+  from breezy import (
+      branch as _mod_branch,
+      option,
+      workingtree,
+      )
+  """)
+
+Lazy importing only works for packages and modules, not classes or
+functions. It defers the import until you actually need it.
+
+
+Learning more
+-------------
+
+`Integrating with Bazaar <http://wiki.bazaar.canonical.com/Integrating_with_Bazaar>`_
+explains how to do such operations as ``add``, ``commit``, ``log`` and more.
+
+Reference documentation on some key APIs is provided below. For a more
+detailed reference, see the `complete breezy API documentation <api/index>`_.
+
+
+Mini API Reference
+------------------
+
+Command Class
+~~~~~~~~~~~~~
+
+Base class for commands. Commands are the heart of the command-line brz
+interface.
+
+The command object mostly handles the mapping of command-line parameters into
+one or more breezy operations, and of the results into textual output.
+
+Commands normally don't have any state. All their arguments are passed in to
+the run method. (Subclasses may take a different policy if the behaviour of the
+instance needs to depend on e.g. a shell plugin and not just its Python class.)
+
+The docstring for an actual command should give a single-line summary, then a
+complete description of the command. A grammar description will be inserted.
+
+aliases
+    Other accepted names for this command.
+
+takes_args
+    List of argument forms, marked with whether they are optional,
+    repeated, etc.
+
+    For example: ``['to_location', 'from_branch?', 'file*']`` means:
+
+    * 'to_location' is required
+    * 'from_branch' is optional
+    * 'file' can be specified 0 or more times
+
+takes_options
+    List of options that may be given for this command. These can be either
+    strings, referring to globally-defined options, or option objects.
+    Retrieve through options().
+
+hidden
+    If true, this command isn't advertised. This is typically for commands
+    intended for expert users.
+
+run()
+    Actually run the command. This is invoked with the options and arguments
+    bound to keyword parameters.
+
+    Return 0 or None if the command was successful, or a non-zero shell error
+    code if not. It's OK for this method to allow an exception to raise up.
+
+
+register_command Function
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Utility function to help register a command.
+
+param *cmd*
+  Command subclass to register
+
+param *decorate*
+  If true, allow overriding an existing command of the same name; the old
+  command is returned by this function. Otherwise it is an error to try to
+  override an existing command.
 
=== modified file 'doc/en/_templates/index.html'
--- doc/en/_templates/index.html	2018-11-18 13:17:18 +0000
+++ doc/en/_templates/index.html	2018-11-22 02:24:44 +0000
@@ -45,12 +45,12 @@
         <p class="biglink"><a class="biglink" href="https://answers.launchpad.net/brz/+faqs">FAQ</a><br/>
       <span class="linkdescr">frequently asked questions</span>
       </p>
-      <p class="biglink"><a class="biglink" href="http://wiki.bazaar.canonical.com/brzGlossary/">Glossary</a><br/>
+      <p class="biglink"><a class="biglink" href="user-reference/glossary-help.html">Glossary</a><br/>
       <span class="linkdescr">help with terminology</span>
       </p>
     </td>
     <td width="50%">
-      <p class="biglink"><a class="biglink" href="../developers/">Developer Docs</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("developers/index") }}">Developer Docs</a><br/>
         <span class="linkdescr">improving and extending brz</span>
       </p>
       <p class="biglink"><a class="biglink" href="http://doc.bazaar.canonical.com/migration/en/">Migration Docs</a><br/>
 
=== modified file 'doc/en/tutorials/using_breezy_with_launchpad.txt'
--- doc/en/tutorials/using_breezy_with_launchpad.txt	2018-11-18 13:16:09 +0000
+++ doc/en/tutorials/using_breezy_with_launchpad.txt	2018-11-22 02:24:44 +0000
@@ -410,36 +410,3 @@
 library of 750,000 translated strings, and a community of 19,000
 registered translators can radically cut the time required to
 localise your project into many languages.
-
-
-Summary
-=======
-
-The communities we join, whether off-line or on-line,
-say a lot about the sort of people we are. The flip-side
-to this is that the tools you choose for your community - particularly
-the CDE and version control tool - can have a large impact on who
-joins and how easily they can contribute.
-
-In their own right, Launchpad and Breezy are highly useful tools.
-Together, they can:
-
-* help your community track major assets such as source code and knowledge
-* help it grow by reducing barriers to entry
-* help it interact with related communities.
-
-In particular, Launchpad is a free code hosting service for your Breezy
-branches, branches can be browsed online, branches can be linked to bugs
-and blueprints, and the status of bug-branch relationships can be
-automatically managed by mentioning the bug while committing in Breezy.
-Further integration is under development with the aim of streamlining
-the process from *great idea* to *running code in the hands of end users*.
-
-If you have any feedback on how you'd like to see Breezy and Launchpad
-further integrated, please contact us on the Bazaar mailing list,
[e-mail].
-
-While designed as a free service to support free software projects,
-Canonical may make Launchpad available to commercial software developers
-depending on their requirements. We would be happy to hear from you
-if you think Launchpad would be useful for managing your community.
 
=== modified file 'doc/en/user-guide/hooks.txt'
--- doc/en/user-guide/hooks.txt	2017-05-21 18:10:28 +0000
+++ doc/en/user-guide/hooks.txt	2018-11-22 02:24:44 +0000
@@ -33,7 +33,7 @@
     branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
                                      'My post_push hook')
 
-.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
+.. _write a plugin: ../../developers/plugin-development.html
 
 To use this example, create a file named ``push_hook.py``, and stick it in
 ``plugins`` subdirectory of your configuration directory.  (If you have never
 
=== modified file 'doc/en/user-guide/writing_a_plugin.txt'
--- doc/en/user-guide/writing_a_plugin.txt	2017-05-21 18:10:28 +0000
+++ doc/en/user-guide/writing_a_plugin.txt	2018-11-22 02:24:44 +0000
@@ -40,8 +40,8 @@
 Plugin searching rules
 ----------------------
 
-Bzr will scan ``~/.bazaar/plugins``  and ``breezy/plugins`` for plugins
-by default.  You can override this with  ``BZR_PLUGIN_PATH``
+Breezy will scan ``~/.config/breezy/plugins``  and ``breezy/plugins`` for
+plugins by default.  You can override this with  ``BRZ_PLUGIN_PATH``
 (see `User Reference 
 <../user-reference/configuration-help.html#brz-plugin-path>`_ for details).
 
@@ -53,7 +53,7 @@
 More information
 ----------------
 
-Please feel free to contribute your plugin to BzrTools, if you think it
+Please feel free to contribute your plugin to Breezy, if you think it
 would be useful to other people.
 
 See the `Breezy Developer Guide`_ for details on Breezy's development