Merge lp:~jelmer/brz/yet-more-docs into lp:brz
- yet-more-docs
- Merge into trunk
Proposed by
Jelmer Vernooij
Status: | Merged |
---|---|
Approved by: | Jelmer Vernooij |
Approved revision: | no longer in the source branch. |
Merge reported by: | The Breezy Bot |
Merged at revision: | not available |
Proposed branch: | lp:~jelmer/brz/yet-more-docs |
Merge into: | lp:brz |
Diff against target: |
415 lines (+275/-44) 8 files modified
doc/developers/index-plain.txt (+2/-2) doc/developers/index.txt (+1/-1) doc/developers/plugin-api.txt (+2/-2) doc/developers/plugin-development.txt (+264/-0) doc/en/_templates/index.html (+2/-2) doc/en/tutorials/using_breezy_with_launchpad.txt (+0/-33) doc/en/user-guide/hooks.txt (+1/-1) doc/en/user-guide/writing_a_plugin.txt (+3/-3) |
To merge this branch: | bzr merge lp:~jelmer/brz/yet-more-docs |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Martin Packman | Approve | ||
Review via email: mp+359087@code.launchpad.net |
Commit message
Some more minor improvements to the docs.
Description of the change
Some more minor improvements to the docs:
* Fix links to glossary and developer docs
* Drop canonical-specific blurb from Launchpad tutorial
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 'doc/developers/index-plain.txt' |
2 | --- doc/developers/index-plain.txt 2018-11-18 14:23:08 +0000 |
3 | +++ doc/developers/index-plain.txt 2018-11-22 02:24:44 +0000 |
4 | @@ -28,8 +28,8 @@ |
5 | |
6 | * `Breezy Code Style Guide <code-style.html>`_. |
7 | |
8 | -* `Writing plugins <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ |
9 | - |--| specific advice on writing Breezy plugins. (web link) |
10 | +* `Writing plugins <plugin-development.html>`_ |
11 | + |--| specific advice on writing Breezy plugins. |
12 | |
13 | * `Documenting changes <documenting-changes.html>`_. |
14 | |
15 | |
16 | === modified file 'doc/developers/index.txt' |
17 | --- doc/developers/index.txt 2018-11-18 14:23:08 +0000 |
18 | +++ doc/developers/index.txt 2018-11-22 02:24:44 +0000 |
19 | @@ -60,7 +60,7 @@ |
20 | overview |
21 | integration |
22 | |
23 | -* `Writing plugins for Breezy <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ (web link) |
24 | +* `Writing plugins for Breezy <plugin-development.txt>`_ |
25 | |
26 | * `breezy API reference <api/index.txt>`_ |
27 | |
28 | |
29 | === modified file 'doc/developers/plugin-api.txt' |
30 | --- doc/developers/plugin-api.txt 2018-11-18 18:23:32 +0000 |
31 | +++ doc/developers/plugin-api.txt 2018-11-22 02:24:44 +0000 |
32 | @@ -23,7 +23,7 @@ |
33 | -------- |
34 | |
35 | * `Breezy Developer Documentation Catalog <../index.html>`_. |
36 | - * `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_ for |
37 | + * `Breezy Plugins Guide <plugin-development.txt>`_ for |
38 | more suggestions about particular APIs. |
39 | |
40 | |
41 | @@ -241,7 +241,7 @@ |
42 | time other than register or override functions to be called later. |
43 | |
44 | The plugin can import breezy and call any function. |
45 | -Some interesting APIs are described in `Breezy Plugins Guide <http://doc.bazaar.canonical.com/plugins/en/plugin-development.html>`_. |
46 | +Some interesting APIs are described in `Breezy Plugins Guide <plugin-development.txt>`_. |
47 | |
48 | |
49 | Publishing your plugin |
50 | |
51 | === added file 'doc/developers/plugin-development.txt' |
52 | --- doc/developers/plugin-development.txt 1970-01-01 00:00:00 +0000 |
53 | +++ doc/developers/plugin-development.txt 2018-11-22 02:24:44 +0000 |
54 | @@ -0,0 +1,264 @@ |
55 | +Developing a plugin |
56 | +=================== |
57 | + |
58 | +Naming |
59 | +------ |
60 | + |
61 | +By convention, most plugins are named brz-xxx and are installed into a |
62 | +directory called xxx. Note that the directory name must be a legal |
63 | +Python package name, so a plugin called brz-xxx-yyy need to be installed |
64 | +into a directory called xxx_yyy, i.e. '-' in a plugin name should be mapped to |
65 | +an underscore in the directory name. |
66 | + |
67 | + |
68 | +Licensing |
69 | +--------- |
70 | + |
71 | +We encourage plugin authors to make their plugins publicly available |
72 | +under the same license as Breezy itself, namely GPL v2 or later. However, there |
73 | +is no requirement to do so. You are free to create Breezy plugins for |
74 | +private or internal use within your company and not distribute them. |
75 | + |
76 | +By sharing your work, a larger number of people benefit. In our experience, |
77 | +plugin developers also benefit heavily by having more users involved in |
78 | +the design, testing, bug fixing and longer term maintenance. In other words, |
79 | +sharing leads to a better plugin faster. |
80 | + |
81 | + |
82 | +Testing |
83 | +------- |
84 | + |
85 | +To ensure your plugin under development is available to Breezy, set |
86 | +the ``BRZ_PLUGIN_PATH`` environment variable to its parent directory. |
87 | +Alternatively, you may wish to develop your plugin within a directory |
88 | +under your personal plugins area (``~/.bazaar/plugins`` on GNU/Linux) |
89 | +or put a symbolic link in that area pointing to your plugin under |
90 | +test. Finally you can use ``BRZ_PLUGINS_AT`` to point to a specific |
91 | +directory for a specific plugin (separated by your platform's value of |
92 | +os.pathsep), e.g. |
93 | + |
94 | + export BRZ_PLUGINS_AT=qbrz@/home/me/qbrz:explorer@/home/me/explorer |
95 | + |
96 | +You can disable loading plugins with ``BRZ_DISABLE_PLUGINS``. |
97 | + |
98 | +If you want to stop loading all but installed plugins you can use: |
99 | + |
100 | + BRZ_PLUGIN_PATH=-site |
101 | + |
102 | +We also encourage plugin developers to provide tests for their plugin. |
103 | +When you run ``brz selftest``, Breezy will scan all its plugins to see if |
104 | +they contain a function named ``test_suite()``. For each plugin that does, |
105 | +it calls the function and adds any resulting tests to the master test suite. |
106 | +To run just the tests for plugin xxx, the command is:: |
107 | + |
108 | + brz selftest -s bp.xxx |
109 | + |
110 | + |
111 | +Providing help |
112 | +-------------- |
113 | + |
114 | +Plugins in this guide have their documentation automatically |
115 | +generated from the online help provided for a plugin. Sections are |
116 | +ordered as follows: |
117 | + |
118 | +1. High level introduction |
119 | +2. Plugin-specific help topics (COMING SOON) |
120 | +3. Commands defined or extended by the plugin. |
121 | + |
122 | +High level help is specified in the docstring for the ``__init__.py`` module. |
123 | +You can register plugin-specific help topics in ``__init__.py`` like this:: |
124 | + |
125 | + _xxx_tutorial = """XXX Tutorial |
126 | + |
127 | + Welcome to xxx, your new best friend. ... |
128 | + """ |
129 | + topic_registry.register('xxx-tutorial', |
130 | + _xxx_tutorial, |
131 | + 'How to use xxx') |
132 | + |
133 | +Command level help is specified in the docstring for the relevant |
134 | +``cmd_xxx`` Command class. |
135 | + |
136 | +.. note:: |
137 | + |
138 | + The final documentation needs to be in ReST format. Keep in mind though |
139 | + that the documentation should also be readable via ``brz help xxx`` so |
140 | + it's best to keep markup to a reasonable minimum. |
141 | + |
142 | + |
143 | +Providing custom code via hooks |
144 | +------------------------------- |
145 | + |
146 | +Hooks let you provide custom code at certain processing points. |
147 | +The available hook point are documented in the `User Reference |
148 | +<http://doc.bazaar-vcs.org/development/en/user-reference/index.html#hooks>`_. |
149 | + |
150 | +Adding a new hook is done with, for example:: |
151 | + |
152 | + import breezy.branch |
153 | + breezy.branch.Branch.hooks.install_named_hook('post_push', post_push_hook, |
154 | + 'My post_push hook') |
155 | + |
156 | +For more information on how to write hooks, |
157 | +see http://doc.bazaar-vcs.org/development/en/user-guide/hooks.html. |
158 | + |
159 | + |
160 | +Defining a new command |
161 | +---------------------- |
162 | + |
163 | +Breezy commands are defined as subclasses of ``breezy.commands.Command``, the |
164 | +command name is specified by the name of the subclass, and they must be |
165 | +registered into ``brz`` with the ``breezy.commands.register_command`` function |
166 | +at module import time. |
167 | + |
168 | +To define the ``brz foo-bar`` command:: |
169 | + |
170 | + from breezy.commands import Command, register_command |
171 | + |
172 | + class cmd_foo_bar(Command): |
173 | + # see breezy/builtins.py for information about what to put here |
174 | + pass |
175 | + |
176 | + register_command(cmd_foo_bar) |
177 | + |
178 | +If the class name starts with ``cmd_``, the prefix will get dropped |
179 | +and ``_`` will be replaced by ``-`` characters. |
180 | + |
181 | + |
182 | +Managing data |
183 | +------------- |
184 | + |
185 | +Plugin data falls into several categories: |
186 | + |
187 | +* Configuration settings. |
188 | +* Data the user can see and version control. |
189 | +* Data behind the scenes. |
190 | + |
191 | +Configuration settings are often stored in ``branch.conf``, |
192 | +``locations.conf`` or ``bazaar.conf``. |
193 | + |
194 | +User-visible data for a plugin called xxx should be stored in |
195 | +``.bzrmeta/xxx``. If mutiple files are desirable, make ``.bzrmeta/xxx`` |
196 | +a directory or give them a common prefix within ``.bzrmeta``, e.g. |
197 | +``xxx-foo``, ``xxx-bar``. |
198 | + |
199 | +Data managed behind the scenes should be stored in ``.bzr``. |
200 | +Depending on the nature of the data, it may belong in a subdirectory |
201 | +within there, e.g. ``checkout``, ``branch`` or ``repository``. |
202 | +It's your responsibility to ensure behind-the-scenes data is |
203 | +propagated and merged appropriately via custom code. You may want |
204 | +to use existing hooks for this or ask for new hooks to help. |
205 | + |
206 | +Useful metadata |
207 | +--------------- |
208 | + |
209 | +It is highly recommended that plugins define a version number. This |
210 | +is displayed by ``brz plugins`` and by the ``qplugins`` GUI dialog. |
211 | +To do this, define ``version_info`` in ``__init__.py`` like this:: |
212 | + |
213 | + version_info = (1, 2, 0, 'beta', 1) |
214 | + |
215 | +Plugins can also declare other useful metadata such as a mimimum |
216 | +breezy version, new transports and storage formats. See |
217 | +`Plugin API <plugin-api>`_ for details. |
218 | + |
219 | + |
220 | +Performance tips |
221 | +---------------- |
222 | + |
223 | +When brz starts up, it imports every plugin, so plugins can degrade |
224 | +performance when they're not being used. However, sub-modules are not |
225 | +loaded, only the main name. |
226 | + |
227 | +One way you can avoid this slowdown is by putting most of your code |
228 | +in sub-modules, so that the plugin, itself, is small. All you really |
229 | +need in the ``__init__.py`` is the plugin's Command classes, the |
230 | +commands to register them, and the optional ``test_suite()``. |
231 | + |
232 | +Another way to reduce your plugin's overhead is to use the breezy |
233 | +lazy_import functionality. That looks something like this:: |
234 | + |
235 | + from breezy.lazy_import import lazy_import |
236 | + lazy_import(globals(), """ |
237 | + from breezy import ( |
238 | + branch as _mod_branch, |
239 | + option, |
240 | + workingtree, |
241 | + ) |
242 | + """) |
243 | + |
244 | +Lazy importing only works for packages and modules, not classes or |
245 | +functions. It defers the import until you actually need it. |
246 | + |
247 | + |
248 | +Learning more |
249 | +------------- |
250 | + |
251 | +`Integrating with Bazaar <http://wiki.bazaar.canonical.com/Integrating_with_Bazaar>`_ |
252 | +explains how to do such operations as ``add``, ``commit``, ``log`` and more. |
253 | + |
254 | +Reference documentation on some key APIs is provided below. For a more |
255 | +detailed reference, see the `complete breezy API documentation <api/index>`_. |
256 | + |
257 | + |
258 | +Mini API Reference |
259 | +------------------ |
260 | + |
261 | +Command Class |
262 | +~~~~~~~~~~~~~ |
263 | + |
264 | +Base class for commands. Commands are the heart of the command-line brz |
265 | +interface. |
266 | + |
267 | +The command object mostly handles the mapping of command-line parameters into |
268 | +one or more breezy operations, and of the results into textual output. |
269 | + |
270 | +Commands normally don't have any state. All their arguments are passed in to |
271 | +the run method. (Subclasses may take a different policy if the behaviour of the |
272 | +instance needs to depend on e.g. a shell plugin and not just its Python class.) |
273 | + |
274 | +The docstring for an actual command should give a single-line summary, then a |
275 | +complete description of the command. A grammar description will be inserted. |
276 | + |
277 | +aliases |
278 | + Other accepted names for this command. |
279 | + |
280 | +takes_args |
281 | + List of argument forms, marked with whether they are optional, |
282 | + repeated, etc. |
283 | + |
284 | + For example: ``['to_location', 'from_branch?', 'file*']`` means: |
285 | + |
286 | + * 'to_location' is required |
287 | + * 'from_branch' is optional |
288 | + * 'file' can be specified 0 or more times |
289 | + |
290 | +takes_options |
291 | + List of options that may be given for this command. These can be either |
292 | + strings, referring to globally-defined options, or option objects. |
293 | + Retrieve through options(). |
294 | + |
295 | +hidden |
296 | + If true, this command isn't advertised. This is typically for commands |
297 | + intended for expert users. |
298 | + |
299 | +run() |
300 | + Actually run the command. This is invoked with the options and arguments |
301 | + bound to keyword parameters. |
302 | + |
303 | + Return 0 or None if the command was successful, or a non-zero shell error |
304 | + code if not. It's OK for this method to allow an exception to raise up. |
305 | + |
306 | + |
307 | +register_command Function |
308 | +~~~~~~~~~~~~~~~~~~~~~~~~~ |
309 | + |
310 | +Utility function to help register a command. |
311 | + |
312 | +param *cmd* |
313 | + Command subclass to register |
314 | + |
315 | +param *decorate* |
316 | + If true, allow overriding an existing command of the same name; the old |
317 | + command is returned by this function. Otherwise it is an error to try to |
318 | + override an existing command. |
319 | |
320 | === modified file 'doc/en/_templates/index.html' |
321 | --- doc/en/_templates/index.html 2018-11-18 13:17:18 +0000 |
322 | +++ doc/en/_templates/index.html 2018-11-22 02:24:44 +0000 |
323 | @@ -45,12 +45,12 @@ |
324 | <p class="biglink"><a class="biglink" href="https://answers.launchpad.net/brz/+faqs">FAQ</a><br/> |
325 | <span class="linkdescr">frequently asked questions</span> |
326 | </p> |
327 | - <p class="biglink"><a class="biglink" href="http://wiki.bazaar.canonical.com/brzGlossary/">Glossary</a><br/> |
328 | + <p class="biglink"><a class="biglink" href="user-reference/glossary-help.html">Glossary</a><br/> |
329 | <span class="linkdescr">help with terminology</span> |
330 | </p> |
331 | </td> |
332 | <td width="50%"> |
333 | - <p class="biglink"><a class="biglink" href="../developers/">Developer Docs</a><br/> |
334 | + <p class="biglink"><a class="biglink" href="{{ pathto("developers/index") }}">Developer Docs</a><br/> |
335 | <span class="linkdescr">improving and extending brz</span> |
336 | </p> |
337 | <p class="biglink"><a class="biglink" href="http://doc.bazaar.canonical.com/migration/en/">Migration Docs</a><br/> |
338 | |
339 | === modified file 'doc/en/tutorials/using_breezy_with_launchpad.txt' |
340 | --- doc/en/tutorials/using_breezy_with_launchpad.txt 2018-11-18 13:16:09 +0000 |
341 | +++ doc/en/tutorials/using_breezy_with_launchpad.txt 2018-11-22 02:24:44 +0000 |
342 | @@ -410,36 +410,3 @@ |
343 | library of 750,000 translated strings, and a community of 19,000 |
344 | registered translators can radically cut the time required to |
345 | localise your project into many languages. |
346 | - |
347 | - |
348 | -Summary |
349 | -======= |
350 | - |
351 | -The communities we join, whether off-line or on-line, |
352 | -say a lot about the sort of people we are. The flip-side |
353 | -to this is that the tools you choose for your community - particularly |
354 | -the CDE and version control tool - can have a large impact on who |
355 | -joins and how easily they can contribute. |
356 | - |
357 | -In their own right, Launchpad and Breezy are highly useful tools. |
358 | -Together, they can: |
359 | - |
360 | -* help your community track major assets such as source code and knowledge |
361 | -* help it grow by reducing barriers to entry |
362 | -* help it interact with related communities. |
363 | - |
364 | -In particular, Launchpad is a free code hosting service for your Breezy |
365 | -branches, branches can be browsed online, branches can be linked to bugs |
366 | -and blueprints, and the status of bug-branch relationships can be |
367 | -automatically managed by mentioning the bug while committing in Breezy. |
368 | -Further integration is under development with the aim of streamlining |
369 | -the process from *great idea* to *running code in the hands of end users*. |
370 | - |
371 | -If you have any feedback on how you'd like to see Breezy and Launchpad |
372 | -further integrated, please contact us on the Bazaar mailing list, |
373 | -bazaar@lists.canonical.com. |
374 | - |
375 | -While designed as a free service to support free software projects, |
376 | -Canonical may make Launchpad available to commercial software developers |
377 | -depending on their requirements. We would be happy to hear from you |
378 | -if you think Launchpad would be useful for managing your community. |
379 | |
380 | === modified file 'doc/en/user-guide/hooks.txt' |
381 | --- doc/en/user-guide/hooks.txt 2017-05-21 18:10:28 +0000 |
382 | +++ doc/en/user-guide/hooks.txt 2018-11-22 02:24:44 +0000 |
383 | @@ -33,7 +33,7 @@ |
384 | branch.Branch.hooks.install_named_hook('post_push', post_push_hook, |
385 | 'My post_push hook') |
386 | |
387 | -.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html |
388 | +.. _write a plugin: ../../developers/plugin-development.html |
389 | |
390 | To use this example, create a file named ``push_hook.py``, and stick it in |
391 | ``plugins`` subdirectory of your configuration directory. (If you have never |
392 | |
393 | === modified file 'doc/en/user-guide/writing_a_plugin.txt' |
394 | --- doc/en/user-guide/writing_a_plugin.txt 2017-05-21 18:10:28 +0000 |
395 | +++ doc/en/user-guide/writing_a_plugin.txt 2018-11-22 02:24:44 +0000 |
396 | @@ -40,8 +40,8 @@ |
397 | Plugin searching rules |
398 | ---------------------- |
399 | |
400 | -Bzr will scan ``~/.bazaar/plugins`` and ``breezy/plugins`` for plugins |
401 | -by default. You can override this with ``BZR_PLUGIN_PATH`` |
402 | +Breezy will scan ``~/.config/breezy/plugins`` and ``breezy/plugins`` for |
403 | +plugins by default. You can override this with ``BRZ_PLUGIN_PATH`` |
404 | (see `User Reference |
405 | <../user-reference/configuration-help.html#brz-plugin-path>`_ for details). |
406 | |
407 | @@ -53,7 +53,7 @@ |
408 | More information |
409 | ---------------- |
410 | |
411 | -Please feel free to contribute your plugin to BzrTools, if you think it |
412 | +Please feel free to contribute your plugin to Breezy, if you think it |
413 | would be useful to other people. |
414 | |
415 | See the `Breezy Developer Guide`_ for details on Breezy's development |
Thanks! Am aware this is mostly ported over text, but have left some inline comments for things that seem not quite right.