From d0b460f26f5d0622374e9f81650907d22ea7a035 Mon Sep 17 00:00:00 2001 From: Jeremy Tuloup Date: Mon, 20 Apr 2020 13:48:43 +0200 Subject: [PATCH 1/2] Add a list of TLJH plugins to the docs --- docs/contributing/plugins.rst | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index 8c9828f..bdd9331 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -4,7 +4,7 @@ TLJH Plugins ============ -TLJH plugins are the official way to make customized 'spins' or 'stacks' +TLJH plugins are the official way to make customized 'spins' or 'stacks' with TLJH as the base. For example, the earth sciences community can make a plugin that installs commonly used packages, set up authentication and pre-download useful datasets. The mybinder.org community can @@ -19,7 +19,7 @@ plugin functionality. TLJH exposes specific **hooks** that your plugin can provide implementations for. This allows us to have specific hook points in the application that can be explicitly extended by plugins, balancing the need to change TLJH internals in the future with the -stability required for a good plugin ecosystem. +stability required for a good plugin ecosystem. Writing a simple plugins ======================== @@ -38,7 +38,7 @@ we recommend they live in one file. For ``tljh-simple``, the repository's structure should look like: .. code-block:: none - + tljh_simple: - tljh_simple.py - setup.py @@ -47,7 +47,7 @@ For ``tljh-simple``, the repository's structure should look like: The ``README.md`` (or ``README.rst`` file) contains human readable information about what your plugin does for your users. ``LICENSE`` -specifies the license used by your plugin - we recommend the +specifies the license used by your plugin - we recommend the 3-Clause BSD License, since that is what is used by TLJH itself. ``setup.py`` - metadata & registration @@ -78,7 +78,7 @@ This is a mostly standard ``setup.py`` file. ``entry_points={"tljh": ["simple = ----------------------------------- In ``tljh_simple.py``, you provide implementations for whichever hooks -you want to extend. +you want to extend. A hook implementation is a function that has the following characteristics: @@ -93,7 +93,7 @@ in the source repository. This example provides an implementation for the ``tljh_extra_user_conda_packages`` -hook, which can return a list of conda packages that'll be installed in users' +hook, which can return a list of conda packages that'll be installed in users' environment from conda-forge. .. code-block:: python @@ -114,6 +114,17 @@ Publishing plugins Plugins are python packages and should be published on PyPI. Users can also install them directly from GitHub - although this is -not good long term practice. +not good long term practice. -The python package should be named ``tljh-``. \ No newline at end of file +The python package should be named ``tljh-``. + + +List of known plugins +===================== + +If you are looking for a way to extend or customize your TLJH deployment, you might want to look for existing plugins. + +Here is a non-exhaustive list of known TLJH plugins: + +- `tljh-pangeo `_: TLJH Plugin for setting up the Pangeo Stack +- `tljh-voila-gallery `_: TLJH plugin that installs a Voilà Gallery From dc247bc5797616e6132a7327db6216c9802dc1a5 Mon Sep 17 00:00:00 2001 From: Jeremy Tuloup Date: Mon, 20 Apr 2020 13:54:58 +0200 Subject: [PATCH 2/2] Add mention to tljh-plugin topic for plugins --- docs/contributing/plugins.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index bdd9331..c013715 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -127,4 +127,9 @@ If you are looking for a way to extend or customize your TLJH deployment, you mi Here is a non-exhaustive list of known TLJH plugins: - `tljh-pangeo `_: TLJH Plugin for setting up the Pangeo Stack -- `tljh-voila-gallery `_: TLJH plugin that installs a Voilà Gallery +- `tljh-voila-gallery `_: TLJH plugin that installs a gallery of Voilà dashboards + +If you have authored a plugin, please open a PR to add it to this list! + +We also recommend adding the ``tljh-plugin`` topic to the GitHub repository to make it more discoverable: +`https://github.com/topics/tljh-plugin `_