From 28c7a9b778bc7ebee920efdb065a6f9b8466f228 Mon Sep 17 00:00:00 2001 From: Pavithra Eswaramoorthy Date: Tue, 19 Sep 2023 15:54:45 +0530 Subject: [PATCH] Improve Extensions documentation (#362) Co-authored-by: eskild <42120229+iameskild@users.noreply.github.com> --- docs/docs/community/plugins.md | 16 +++++++++ docs/docs/how-tos/nebari-extension-system.md | 37 +++++++++++++------- docs/sidebars.js | 1 + 3 files changed, 41 insertions(+), 13 deletions(-) create mode 100644 docs/docs/community/plugins.md diff --git a/docs/docs/community/plugins.md b/docs/docs/community/plugins.md new file mode 100644 index 000000000..f70547dec --- /dev/null +++ b/docs/docs/community/plugins.md @@ -0,0 +1,16 @@ +--- +id: plugins +title: Plugins (Extensions) +description: List of Nebari plugins +--- + +Nebari plugins (sometimes referred to as extensions) allow developers to add new features relatively easily without the need to modify the core Nebari code base. At the moment, there are two types of plugins `stages` and `subcommands`. Stage plugins allow users to deploy new features alongside the existing the Nebari features whereas subcommand plugins allow users to extend or modify the existing Nebari CLI. + +You can learn to use and create Nebari extensions in the [extension mechanism documentation](/docs/how-tos/nebari-extension-system). + +## Verified community extensions + +The following community-developed extensions are recognized and verified by the Nebari development team. + +* [nebari-mlflow-aws](https://github.com/MetroStar/nebari-mlflow-aws) +* [nebari-label-studio](https://github.com/MetroStar/nebari-label-studio) diff --git a/docs/docs/how-tos/nebari-extension-system.md b/docs/docs/how-tos/nebari-extension-system.md index 6069ca0e1..f3d0b6ded 100644 --- a/docs/docs/how-tos/nebari-extension-system.md +++ b/docs/docs/how-tos/nebari-extension-system.md @@ -4,15 +4,21 @@ title: Nebari Extension System description: An overview of the pluggy extension system for Nebari --- +:::warning +The Extension System was added recently in release 2023.9.1. It's in active development and might be unstable. + +We don't recommend using it in productions systems yet, but we'll appreciate your explorations, testing, and feedback. You can share your comments in [this GitHub Issue](https://github.com/nebari-dev/nebari/issues/1894). +::: + ## Introduction This guide is to help developers extend and modify the behavior of -nebari. We leverage the plugin system +Nebari. We leverage the plugin system [pluggy](https://pluggy.readthedocs.io/en/stable/) to enable easy -extensibility. Currently Nebari supports: +extensibility. Currently, Nebari supports: - overriding a given stages in a deployment - - adding additional stages before, after and between existing stages + - adding additional stages before, after and between existing stages - arbitrary subcommands We maintain an [examples @@ -21,7 +27,7 @@ which contains up to date usable examples. ## Installing a plugin -Registering a plugin should be easy for the end user. Pluggins are +Registering a plugin should be easy for the end user. Plugins are either installed into your existing environment e.g. ```shell @@ -30,7 +36,7 @@ pip install my-nebari-plugin Alternatively if you only want to temporarily add an extension. -:::note +:::note `--import-plugin` does not work for loading subcommands due to cli already being constructed before plugin imports take place. ::: @@ -40,30 +46,35 @@ nebari --import-plugin path/to/plugin.py ... nebari --import-plugin import.module.plugin.path ... ``` +:::note +Currently, Nebari does **not** support un-installing a plugin. +You will need to destroy and re-deploy Nebari to remove any installed plugins. +::: + ## Developing an extension The most important step to developing a plugin is ensuring that the setuptools entrypoint is set. -```toml:pyproject.toml + +```yaml title="pyproject.toml" ... [project.entry-points.nebari] my-subcommand = "path.to.subcommand.module" ... - ``` Adding this one line to your `pyproject.toml` will ensure that upon -installation of the package the nebari plugins are registered. +installation of the package the Nebari plugins are registered. ### Subcommands Nebari exposes a hook `nebari_subcommand` which exposes the -[typer](https://github.com/tiangolo/typer) cli instance. This allows -the developer to attach and arbitrary number of subcommands. +[typer](https://github.com/tiangolo/typer) CLI instance. This allows +the developer to attach any arbitrary number of subcommands. ```python from nebari.hookspecs import hookimpl @@ -87,14 +98,14 @@ There is a dedicated working example in [nebari-plugin-examples](https://github. ### Stages Nebari exposes a hook `nebari_stage` which uses the `NebariStage` -class. The `NebriStage` exposes `render`, `deploy`, `destroy` as -arbitrary functions called. See below for a complete example. +class. `NebriStage` exposes `render`, `deploy`, `destroy` as +arbitrary functions calls. See below for a complete example. Nebari decides the order of stages based on two things the `name: str` attribute and `priority: int` attribute. The rules are as follows: - stages are ordered by `priority` - stages which have the same `name` the one with highest priority - number is chosen. + number is chosen ```python import contextlib diff --git a/docs/sidebars.js b/docs/sidebars.js index 93dbd2278..3678291ca 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -115,6 +115,7 @@ module.exports = { "community/doc-contributions", "community/style-guide", "community/team-structure", + "community/plugins", { type: "category", label: "Maintainers",