@@ -2,21 +2,21 @@ Implementing hooks and writing internal plugins
22***********************************************
33Implementing a hook is fairly simple, and works the same way regardless of what
44type of hook it is (core or extension). If you are working with your own fork
5- of ``repomate ``, all you have to do is write a small module implementing some hooks,
6- and drop it into the ``repomate .ext
7- ``repomate /extrepomate `` repo).
5+ of ``repobee ``, all you have to do is write a small module implementing some hooks,
6+ and drop it into the ``repobee .ext
7+ ``repobee /extrepobee `` repo).
88
99There are two ways to implement hooks: as standalone functions or wrapped in a
1010class. In the following two sections, we'll implement the
11- :py:func: `~repomate_plug .exthooks.CloneHook.act_on_cloned_repo ` extension hook
11+ :py:func: `~repobee_plug .exthooks.CloneHook.act_on_cloned_repo ` extension hook
1212using both techniques. Let's call the plugin ``exampleplug `` and make sure it
1313adheres to the plugin conventions.
1414
1515Hook functions in a plugin class
1616================================
1717Wrapping hook implementations in a class inheriting from
18- :py:class: `~repomate_plug .pluginmeta.Plugin ` is the recommended way to write
19- plugins for ``repomate ``. The class does some checks to make sure that all
18+ :py:class: `~repobee_plug .pluginmeta.Plugin ` is the recommended way to write
19+ plugins for ``repobee ``. The class does some checks to make sure that all
2020public functions have hook function names, which comes in handy if you are
2121in the habit of misspelling stuff (aren't we all?). Doing it this way,
2222``exampleplug.py `` would look like this:
@@ -28,7 +28,7 @@ in the habit of misspelling stuff (aren't we all?). Doing it this way,
2828 import os
2929 from typing import Union
3030
31- import repomate_plug as plug
31+ import repobee_plug as plug
3232
3333 PLUGIN_NAME = ' exampleplug'
3434
@@ -47,30 +47,30 @@ in the habit of misspelling stuff (aren't we all?). Doing it this way,
4747 return plug.HookResult(
4848 hook = PLUGIN_NAME , status = plug.Status.WARNING , msg = " This isn't quite done"
4949
50- exampleplug.py `` into the ``repomate .ext
51- ``repomate -p exampleplug clone [ADDITIONAL ARGS]
50+ exampleplug.py `` into the ``repobee .ext
51+ ``repobee -p exampleplug clone [ADDITIONAL ARGS]
5252not-so-interesting output from the plugin.
5353
5454The name of the class really doesn't matter, it just needs to inherit from
55- :py:class: `~repomate_plug .pluginmeta.Plugin `. The name of the module and hook
55+ :py:class: `~repobee_plug .pluginmeta.Plugin `. The name of the module and hook
5656functions matter, though. The name of the module must be the plugin name, and
5757the hook functions must have the precise names of the hooks they implement. In
5858fact, all public methods in a class deriving from
59- :py:class: `~repomate_plug .pluginmeta.Plugin ` must have names of hook functions,
59+ :py:class: `~repobee_plug .pluginmeta.Plugin ` must have names of hook functions,
6060or the class will fail to be created. You can see that the hook returns a
61- :py:class: `~repomate_plug .util.HookResult `. This is used for reporting the
62- results in ``repomate ``, and is entirely optional (not all hooks support it,
63- though). Do note that if ``None `` is returned instead, ``repomate `` will not
61+ :py:class: `~repobee_plug .util.HookResult `. This is used for reporting the
62+ results in ``repobee ``, and is entirely optional (not all hooks support it,
63+ though). Do note that if ``None `` is returned instead, ``repobee `` will not
6464report anything for the hook. It is recommended that hooks that can return
6565``HookResult `` do. For a comprehensive example of an internal plugin
6666implemented with a class, see the built-in `javac plugin `_.
6767
6868Standalone hook functions
6969=========================
7070Using standalone hook functions is recommended only if you don't want the
71- safety net provided by the :py:class: `~repomate_plug .pluginmeta.Plugin `
71+ safety net provided by the :py:class: `~repobee_plug .pluginmeta.Plugin `
7272metaclass. It is fairly straightforward: simply mark a function with the
73- :py:const: `repomate_plug.repomate_hook ` decorator. With this approach,
73+ :py:const: `repobee_plug.repobee_hook ` decorator. With this approach,
7474``exampleplug.py `` would look like this:
7575
7676.. code-block :: python
@@ -80,11 +80,11 @@ metaclass. It is fairly straightforward: simply mark a function with the
8080 import os
8181 from typing import Union
8282
83- import repomate_plug as plug
83+ import repobee_plug as plug
8484
8585 PLUGIN_NAME = ' exampleplug'
8686
87- @plug.repomate_hook
87+ @plug.repobee_hook
8888 def act_on_cloned_repo (path : Union[str , pathlib.Path]) -> plug.HookResult:
8989 """ Do something with a cloned repo.
9090
@@ -96,12 +96,12 @@ metaclass. It is fairly straightforward: simply mark a function with the
9696 return plug.HookResult(
9797 hook = PLUGIN_NAME , status = plug.Status.WARNING , msg = " This isn't quite done"
9898
99- exampleplug.py `` into the ``repomate .ext
100- ``repomate -p exampleplug clone [ADDITIONAL ARGS]
99+ exampleplug.py `` into the ``repobee .ext
100+ ``repobee -p exampleplug clone [ADDITIONAL ARGS]
101101not-so-interesting output from the plugin. For a more practical example of a
102102plugin implemented using only a hook function, see the built-in `pylint
103103plugin `_.
104104
105- .. _ repomate -junit4https://github.com/slarse/repomate -junit4
106- .. _javac plugin : https://github.com/slarse/repomate /blob/master/repomate /ext/javac.py
107- .. _pylint plugin : https://github.com/slarse/repomate /blob/master/repomate /ext/pylint.py
105+ .. _ repobee -junit4https://github.com/repobee/repobee -junit4
106+ .. _javac plugin : https://github.com/repobee/repobee /blob/master/repobee /ext/javac.py
107+ .. _pylint plugin : https://github.com/repobee/repobee /blob/master/repobee /ext/pylint.py
0 commit comments