mirror of
https://github.com/lensapp/lens.git
synced 2025-05-20 05:10:56 +00:00
Remove docs from lens repo
- Remove all docs apart from extension api auto-generated related docs. All standard Lens IDE docs will now reside in lens-ide repo; - Remove the delete and set-version workflows for the docs. These will now reside in the lens-ide repo; - Amend the existing workflow that builds/publishes the docs to instead create a repository dispatch event to the lens-ide repo. This event will be the trigger for the build/publish docs workflow in lens-ide repo Signed-off-by: Steve Richards <srichards@mirantis.com>
This commit is contained in:
1 parent
5372e3617e
commit
c9c55842da
78 files changed
+14
-3885
No files matched your search
@@ -1,116 +0,0 @@
|
||||
# Extension Anatomy
|
||||
|
||||
In the [previous section](your-first-extension.md) you learned how to create your first extension.
|
||||
In this section you will learn how this extension works under the hood.
|
||||
|
||||
The Hello World sample extension does three things:
|
||||
|
||||
- Implements `onActivate()` and outputs a message to the console.
|
||||
- Implements `onDectivate()` and outputs a message to the console.
|
||||
- Registers `ClusterPage` so that the page is visible in the left-side menu of the cluster dashboard.
|
||||
|
||||
Let's take a closer look at our Hello World sample's source code and see how these three things are achieved.
|
||||
|
||||
## Extension File Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── .gitignore // Ignore build output and node_modules
|
||||
├── Makefile // Config for build tasks that compiles the extension
|
||||
├── README.md // Readable description of your extension's functionality
|
||||
├── src
|
||||
│ └── page.tsx // Extension's additional source code
|
||||
├── main.ts // Source code for extension's main entrypoint
|
||||
├── package.json // Extension manifest and dependencies
|
||||
├── renderer.tsx // Source code for extension's renderer entrypoint
|
||||
├── tsconfig.json // TypeScript configuration
|
||||
├── webpack.config.js // Webpack configuration
|
||||
```
|
||||
|
||||
The extension directory contains the extension's entry files and a few configuration files.
|
||||
Three files: `package.json`, `main.ts` and `renderer.tsx` are essential to understanding the Hello World sample extension.
|
||||
We'll look at those first.
|
||||
|
||||
### Extension Manifest
|
||||
|
||||
Each Lens extension must have a `package.json` file.
|
||||
It contains a mix of Node.js fields, including scripts and dependencies, and Lens-specific fields such as `publisher` and `contributes`.
|
||||
Some of the most-important fields include:
|
||||
|
||||
- `name` and `publisher`: Lens uses `@<publisher>/<name>` as a unique ID for the extension.
|
||||
For example, the Hello World sample has the ID `@lensapp-samples/helloworld-sample`.
|
||||
Lens uses this ID to uniquely identify your extension.
|
||||
- `main`: the extension's entry point run in `main` process.
|
||||
- `renderer`: the extension's entry point run in `renderer` process.
|
||||
- `engines.lens`: the minimum version of Lens API that the extension depends upon.
|
||||
|
||||
``` javascript
|
||||
{
|
||||
"name": "helloworld-sample",
|
||||
"publisher": "lens-samples",
|
||||
"version": "0.0.1",
|
||||
"description": "Lens helloworld-sample",
|
||||
"license": "MIT",
|
||||
"homepage": "https://github.com/lensapp/lens-extension-samples",
|
||||
"engines": {
|
||||
"lens": "^4.0.0"
|
||||
},
|
||||
"main": "dist/main.js",
|
||||
"renderer": "dist/renderer.js",
|
||||
"scripts": {
|
||||
"build": "webpack --config webpack.config.js",
|
||||
"dev": "npm run build --watch"
|
||||
},
|
||||
"dependencies": {
|
||||
"react-open-doodles": "^1.0.5"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@k8slens/extensions": "^4.0.0-alpha.2",
|
||||
"ts-loader": "^8.0.4",
|
||||
"typescript": "^4.0.3",
|
||||
"@types/react": "^16.9.35",
|
||||
"@types/node": "^12.0.0",
|
||||
"webpack": "^4.44.2",
|
||||
"webpack-cli": "^3.3.11"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Extension Entry Files
|
||||
|
||||
Lens extensions can have two separate entry files.
|
||||
One file is used in the `main` process of the Lens application and the other is used in the `renderer` process.
|
||||
The `main` entry file exports the class that extends `LensMainExtension`, and the `renderer` entry file exports the class that extends `LensRendererExtension`.
|
||||
|
||||
Both extension classes have `onActivate` and `onDeactivate` methods.
|
||||
The `onActivate` method is executed when your extension is activated.
|
||||
If you need to initialize something in your extension, this is where such an operation should occur.
|
||||
The `onDeactivate` method gives you a chance to clean up before your extension becomes deactivated.
|
||||
For extensions where explicit cleanup is not required, you don't need to override this method.
|
||||
However, if an extension needs to perform an operation when Lens is shutting down (or if the extension is disabled or uninstalled), this is the method where such an operation should occur.
|
||||
|
||||
The Hello World sample extension does not do anything on the `main` process, so we'll focus on the `renderer` process, instead.
|
||||
On the `renderer` entry point, the Hello World sample extension defines the `Cluster Page` object.
|
||||
The `Cluster Page` object registers the `/extension-example` path, and this path renders the `ExamplePage` React component.
|
||||
It also registers the `MenuItem` component that displays the `ExampleIcon` React component and the "Hello World" text in the left-side menu of the cluster dashboard.
|
||||
These React components are defined in the additional `./src/page.tsx` file.
|
||||
|
||||
``` typescript
|
||||
import { LensRendererExtension } from "@k8slens/extensions";
|
||||
import { ExampleIcon, ExamplePage } from "./page"
|
||||
import React from "react"
|
||||
|
||||
export default class ExampleExtension extends LensRendererExtension {
|
||||
clusterPages = [
|
||||
{
|
||||
id: "extension-example",
|
||||
components: {
|
||||
Page: () => <ExamplePage extension={this}/>,
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The Hello World sample extension uses the `Cluster Page` capability, which is just one of the Lens extension API's capabilities.
|
||||
The [Common Capabilities](../capabilities/common-capabilities.md) page will help you home in on the right capabilities to use with your own extensions.
|
||||
@@ -1,27 +0,0 @@
|
||||
# Extension Development Overview
|
||||
|
||||
This is a general overview to how the development of an extension will proceed.
|
||||
For building extensions there will be a few things that you should have installed, and some other things that might be of help.
|
||||
|
||||
### Required:
|
||||
- [Node.js](https://www.nodejs.org/en/)
|
||||
- [Git](https://www.git-scm.com/)
|
||||
- Some sort of text editor – we recommend [VSCode](https://code.visualstudio.com/)
|
||||
- We use [Webpack](https://www.webpack.js.org/) for compilation.
|
||||
All extension need to be at least compatible with a webpack system.
|
||||
|
||||
### Recommended:
|
||||
|
||||
All Lens extensions are javascript packages.
|
||||
We recommend that you program in [Typescript](https://www.typescriptlang.org/) because it catches many common errors.
|
||||
|
||||
Lens is a standard [Electron](https://www.electronjs.org/) application with both main and renderer processes.
|
||||
An extension is made up of two parts, one for each of Lens's core processes.
|
||||
When an extension is loaded, each part is first loaded and issues a notification that it has been loaded.
|
||||
From there, the extension can start doing is work.
|
||||
|
||||
Lens uses [React](https://www.reactjs.org/) as its UI framework and provides some of Lens's own components for reuse with extensions.
|
||||
An extension is responsible for the lifetime of any resources it spins up.
|
||||
If an extension's main part starts new processes they all must be stopped and cleaned up when the extension is deactivated or unloaded.
|
||||
|
||||
See [Your First Extension](your-first-extension.md) to get started.
|
||||
@@ -1,24 +0,0 @@
|
||||
# Wrapping Up
|
||||
|
||||
In [Your First Extension](your-first-extension.md), you learned how to create and run an extension.
|
||||
In [Extension Anatomy](anatomy.md), you learned in detail how a basic extension works.
|
||||
This is just a glimpse into what can be created with Lens extensions.
|
||||
Below are some suggested routes for learning more.
|
||||
|
||||
## Extension Capabilities
|
||||
|
||||
In this section, you'll find information on common extension capabilities, styling information, and a color reference guide.
|
||||
Determine whether your idea for an extension is doable and get ideas for new extensions by reading through the [Common Capabilities](../capabilities/common-capabilities.md) page.
|
||||
|
||||
## Guides and Samples
|
||||
|
||||
Here you'll find a collection of sample extensions that you can use as a base to work from.
|
||||
Some of these samples include a detailed guide that explains the source code.
|
||||
You can find all samples and guides in the [lens-extension-samples](https://github.com/lensapp/lens-extension-samples) repository.
|
||||
|
||||
## Testing and Publishing
|
||||
|
||||
In this section, you can learn:
|
||||
|
||||
* How to add [integration tests](../testing-and-publishing/testing.md) to your extension
|
||||
* How to [publish your extension](../testing-and-publishing/publishing.md)
|
||||
@@ -1,100 +0,0 @@
|
||||
# Your First Extension
|
||||
|
||||
We recommend to always use [Yeoman generator for Lens Extension](https://github.com/lensapp/generator-lens-ext) to start new extension project.
|
||||
[Read the generator guide here](../guides/generator.md).
|
||||
|
||||
If you want to setup the project manually, please continue reading.
|
||||
|
||||
## First Extension
|
||||
|
||||
In this topic, you'll learn the basics of building extensions by creating an extension that adds a "Hello World" page to a cluster menu.
|
||||
|
||||
## Install the Extension
|
||||
|
||||
To install the extension, clone the [Lens Extension samples](https://github.com/lensapp/lens-extension-samples) repository to your local machine:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/lensapp/lens-extension-samples.git
|
||||
```
|
||||
|
||||
Next you need to create a symlink.
|
||||
A symlink connects the directory that Lens will monitor for user-installed extensions to the sample extension.
|
||||
In this case the sample extension is `helloworld-sample`.
|
||||
|
||||
### Linux & macOS
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.k8slens/extensions
|
||||
cd ~/.k8slens/extensions
|
||||
ln -s lens-extension-samples/helloworld-sample helloworld-sample
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
Create the directory that Lens will monitor for user-installed extensions:
|
||||
|
||||
```sh
|
||||
mkdir C:\Users\<user>\.k8slens\extensions -force
|
||||
cd C:\Users\<user>\.k8slens\extensions
|
||||
```
|
||||
|
||||
If you have administrator rights, you can create symlink to the sample extension – in this case `helloworld-sample`:
|
||||
|
||||
```sh
|
||||
cmd /c mklink /D helloworld-sample lens-extension-samples\helloworld-sample
|
||||
```
|
||||
|
||||
Without administrator rights, you need to copy the extensions sample directory into `C:\Users\<user>\.k8slens\extensions`:
|
||||
|
||||
```
|
||||
Copy-Item 'lens-extension-samples\helloworld-sample' 'C:\Users\<user>\.k8slens\extensions\helloworld-sample'
|
||||
```
|
||||
|
||||
## Build the Extension
|
||||
|
||||
To build the extension you can use `make` or run the `npm` commands manually:
|
||||
|
||||
```sh
|
||||
cd <lens-extension-samples directory>/helloworld-sample
|
||||
make build
|
||||
```
|
||||
|
||||
To run the `npm` commands, enter:
|
||||
|
||||
```sh
|
||||
cd <lens-extension-samples directory>/helloworld-sample
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
Optionally, automatically rebuild the extension by watching for changes to the source code.
|
||||
To do so, enter:
|
||||
|
||||
```sh
|
||||
cd <lens-extension-samples directory>/helloworld-sample
|
||||
npm run dev
|
||||
```
|
||||
|
||||
You must restart Lens for the extension to load.
|
||||
After this initial restart, reload Lens and it will automatically pick up changes any time the extension rebuilds.
|
||||
|
||||
With Lens running, either connect to an existing cluster or [create a new one](../../clusters/adding-clusters.md).
|
||||
You will see the "Hello World" page in the left-side cluster menu.
|
||||
|
||||
## Develop the Extension
|
||||
|
||||
Finally, you'll make a change to the message that our Hello World sample extension displays:
|
||||
|
||||
1. Navigate to `<lens-extension-samples directory>/helloworld-sample`.
|
||||
2. In `page.tsx`, change the message from `HelloWorld!` to `Hello Lens Extensions`.
|
||||
3. Rebuild the extension. If you used `npm run dev`, the extension will rebuild automatically.
|
||||
4. Reload the Lens window.
|
||||
5. Click on the Hello World page.
|
||||
6. The updated message will appear.
|
||||
|
||||
## Next Steps
|
||||
|
||||
In the [next topic](anatomy.md), we'll take a closer look at the source code of our Hello World sample.
|
||||
|
||||
You can find the source code for this tutorial at: [lensapp/lens-extension-samples](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample).
|
||||
[Extension Guides](../guides/README.md) contains additional samples.
|
||||
Reference in new issue
Block a user