hendrik/lens
1
0 Fork 0
mirror of https://github.com/lensapp/lens.git synced 2025-05-20 05:10:56 +00:00
Code Issues Projects Releases Wiki Activity

Reworked remaining docs (#1402)

Browse Source 
Signed-off-by: Paul Williams <pawilliams@mirantis.com>
This commit is contained in:
pauljwil authored and GitHub committed 2020-11-17 08:48:24 +02:00
1 parent 246227168a
commit 532b10e357
10 files changed
+82 -79
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/extensions/README.md
+2 -3
View File
@@ -20,12 +20,11 @@ For an overview of the Lens Extension API, refer to the [Common Capabilities](ca
Here is what each section of the Lens Extension API docs can help you with:
* **Get Started** teaches fundamental concepts for building extensions with the Hello World sample.
* **Getting Started** teaches fundamental concepts for building extensions with the Hello World sample.
* **Extension Capabilities** dissects Lens's Extension API into smaller categories and points you to more detailed topics.
* **Extension Guides** includes guides and code samples that explain specific usages of Lens Extension API.
* **Testing and Publishing** includes in-depth guides on various extension development topics, such as testing and publishing extensions.
* **Advanced Topics** explains advanced concepts such as integrating with 3rd party applications/services.
* **References** contains exhaustive references for the Lens Extension API, Contribution Points, and many other topics.
* **API Reference** contains exhaustive references for the Lens Extension API, Contribution Points, and many other topics.
## What's New
docs/extensions/capabilities/color-reference.md
+14 -14
View File
@@ -1,7 +1,7 @@
# Theme color reference
# Theme Color Reference
You can use theme-based CSS Variables to style an extension according to the active theme.
## Base colors
## Base Colors
- `--blue`: blue color.
- `--magenta`: magenta color.
- `--golden`: gold/yellow color.
@@ -17,16 +17,16 @@ You can use theme-based CSS Variables to style an extension according to the act
- `--colorTerminated`: terminated, closed, stale color.
- `--boxShadow`: semi-transparent box-shadow color.
## Text colors
## Text Colors
- `--textColorPrimary`: foreground text color.
- `--textColorSecondary`: foreground text color for different paragraps, parts of text.
- `--textColorAccent`: foreground text color to highlight its parts.
## Border colors
## Border Colors
- `--borderColor`: border color.
- `--borderFaintColor`: fainted (lighter or darker, which depends on the theme) border color.
## Layout colors
## Layout Colors
- `--mainBackground`: main background color for the app.
- `--contentColor`: background color for panels contains some data.
- `--layoutBackground`: background color for layout parts.
@@ -34,19 +34,19 @@ You can use theme-based CSS Variables to style an extension according to the act
- `--layoutTabsActiveColor`: foreground color for general tabs.
- `--layoutTabsLineColor`: background color for lines under general tabs.
## Sidebar colors
## Sidebar Colors
- `--sidebarLogoBackground`: background color behind logo in sidebar.
- `--sidebarActiveColor`: foreground color for active menu items in sidebar.
- `--sidebarSubmenuActiveColor`: foreground color for active submenu items in sidebar.
- `--sidebarBackground`: background color for sidebar.
## Button colors
## Button Colors
- `--buttonPrimaryBackground`: button background color for primary actions.
- `--buttonDefaultBackground`: default button background color.
- `--buttonAccentBackground`: accent button background color.
- `--buttonDisabledBackground`: disabled button background color.
## Table colors
## Table Colors
- `--tableBgcStripe`: background color for odd rows in table.
- `--tableBgcSelected`: background color for selected row in table.
- `--tableHeaderBackground`: background color for table header.
@@ -55,12 +55,12 @@ You can use theme-based CSS Variables to style an extension according to the act
- `--tableHeaderColor`: foreground color for table header.
- `--tableSelectedRowColor`: foreground color for selected row in table.
## Dock colors
## Dock Colors
- `--dockHeadBackground`: background color for dock's header.
- `--dockInfoBackground`: background color for dock's info panel.
- `--dockInfoBorderColor`: border color for dock's info panel.
## Helm chart colors
## Helm Chart Colors
- `--helmLogoBackground`: background color for chart logo.
- `--helmImgBackground`: background color for chart image.
- `--helmStableRepo`: background color for stable repo.
@@ -77,7 +77,7 @@ You can use theme-based CSS Variables to style an extension according to the act
- `--helmDescriptionPreBackground`: Helm chart description pre background color.
- `--helmDescriptionPreColor`: Helm chart description pre foreground color.
## Terminal colors
## Terminal Colors
- `--terminalBackground`: Terminal background color.
- `--terminalForeground`: Terminal foreground color.
- `--terminalCursor`: Terminal cursor color.
@@ -100,17 +100,17 @@ You can use theme-based CSS Variables to style an extension according to the act
- `--terminalBrightCyan`: Terminal bright cyan color.
- `--terminalBrightWhite`: Terminal bright white color.
## Dialog colors
## Dialog Colors
- `--dialogHeaderBackground`: background color for dialog header.
- `--dialogFooterBackground`: background color for dialog footer.
## Detail panel (Drawer) colors
## Detail Panel (Drawer) Colors
- `--drawerTitleText`: drawer title foreground color.
- `--drawerSubtitleBackground`: drawer subtitle foreground color.
- `--drawerItemNameColor`: foreground color for item name in drawer.
- `--drawerItemValueColor`: foreground color for item value in drawer.
## Misc colors
## Misc Colors
- `--logsBackground`: background color for pod logs.
- `--clusterMenuBackground`: background color for cluster menu.
- `--clusterMenuBorderColor`: border color for cluster menu.
docs/extensions/capabilities/common-capabilities.md
+15 -15
View File
@@ -1,14 +1,14 @@
# Common Capabilities
Common Capabilities are important building blocks for your extensions. Almost all extensions use some of these functionalities. Here is how you can take advantage of them.
Here we will discuss common and important building blocks for your extensions, and explain how you can use them. Almost all extensions use some of these functionalities.
## Main Extension
A main extension runs in the background and, apart from app menu items, does not add content to the Lens UI. If you want to see logs from this extension you need to start Lens from the command line.
The main extension runs in the background. It adds app menu items to the Lens UI. In order to see logs from this extension, you need to start Lens from the command line.
### Activate
An extension can register a custom callback that is executed when an extension is activated (started).
This extension can register a custom callback that is executed when an extension is activated (started).
``` javascript
import { LensMainExtension } from "@k8slens/extensions"
@@ -22,7 +22,7 @@ export default class ExampleMainExtension extends LensMainExtension {
### Deactivate
An extension can register a custom callback that is executed when an extension is deactivated (stopped).
This extension can register a custom callback that is executed when an extension is deactivated (stopped).
``` javascript
import { LensMainExtension } from "@k8slens/extensions"
@@ -36,7 +36,7 @@ export default class ExampleMainExtension extends LensMainExtension {
### App Menus
An extension can register custom App menus that will be displayed on OS native menus.
This extension can register custom app menus that will be displayed on OS native menus.
Example:
@@ -58,11 +58,11 @@ export default class ExampleMainExtension extends LensMainExtension {
## Renderer Extension
A renderer extension runs in a browser context and it's visible directly via Lens main window. If you want to see logs from this extension you need to check them via View -> Toggle Developer Tools -> Console.
The renderer extension runs in a browser context, and is visible in Lens's main window. In order to see logs from this extension you need to check them via **View** > **Toggle Developer Tools** > **Console**.
### Activate
An extension can register a custom callback that is executed when an extension is activated (started).
This extension can register a custom callback that is executed when an extension is activated (started).
``` javascript
import { LensRendererExtension } from "@k8slens/extensions"
@@ -76,7 +76,7 @@ export default class ExampleExtension extends LensRendererExtension {
### Deactivate
An extension can register a custom callback that is executed when an extension is deactivated (stopped).
This extension can register a custom callback that is executed when an extension is deactivated (stopped).
``` javascript
import { LensRendererExtension } from "@k8slens/extensions"
@@ -90,7 +90,7 @@ export default class ExampleMainExtension extends LensRendererExtension {
### Global Pages
An extension can register custom global pages (views) to Lens main window. Global page is a full screen page that hides all the other content from a window.
This extension can register custom global pages (views) to Lens's main window. The global page is a full-screen page that hides all other content from a window.
``` typescript
import React from "react"
@@ -122,7 +122,7 @@ export default class ExampleRendererExtension extends LensRendererExtension {
### App Preferences
An extension can register custom app preferences. An extension is responsible for storing a state for custom preferences.
This extension can register custom app preferences. It is responsible for storing a state for custom preferences.
``` typescript
import React from "react"
@@ -146,7 +146,7 @@ export default class ExampleRendererExtension extends LensRendererExtension {
### Cluster Pages
An extension can register custom cluster pages which are visible in a cluster menu when a cluster is opened.
This extension can register custom cluster pages. These pages are visible in a cluster menu when a cluster is opened.
``` typescript
import React from "react"
@@ -179,7 +179,7 @@ export default class ExampleExtension extends LensRendererExtension {
### Cluster Features
An extension can register installable features for a cluster. A cluster feature is visible in "Cluster Settings" page.
This extension can register installable features for a cluster. These features are visible in the "Cluster Settings" page.
``` typescript
import React from "react"
@@ -208,7 +208,7 @@ export default class ExampleExtension extends LensRendererExtension {
### Status Bar Items
An extension can register custom icons/texts to a status bar area.
This extension can register custom icons and text to a status bar area.
``` typescript
import React from "react";
@@ -230,7 +230,7 @@ export default class ExampleExtension extends LensRendererExtension {
### Kubernetes Object Menu Items
An extension can register custom menu items (actions) for specified Kubernetes kinds/apiVersions.
This extension can register custom menu items (actions) for specified Kubernetes kinds/apiVersions.
``` typescript
import React from "react"
@@ -253,7 +253,7 @@ export default class ExampleExtension extends LensRendererExtension {
### Kubernetes Object Details
An extension can register custom details (content) for specified Kubernetes kinds/apiVersions.
This extension can register custom details (content) for specified Kubernetes kinds/apiVersions.
``` typescript
import React from "react"
docs/extensions/capabilities/styling.md
+15 -17
View File
@@ -4,14 +4,12 @@ Lens provides a set of global styles and UI components that can be used by any e
## Layout
For layout tasks Lens is using [flex.box](https://www.npmjs.com/package/flex.box) library which provides helpful class names to specify some of the [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) properties. For example, `div` with class names:
For layout tasks, Lens uses the [flex.box](https://www.npmjs.com/package/flex.box) library which provides helpful class names to specify some of the [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) properties. For example, consider the following HTML and its associated CSS properties:
```html
<div className="flex column align-center"></div>
```
at the end will have following css properties:
```css
div {
display: flex;
@@ -20,11 +18,11 @@ div {
}
```
However, feel free to use any styling technique or framework like [Emotion](https://github.com/emotion-js/emotion) or just plain CSS if you prefer.
However, you are free to use any styling technique or framework you like, including [Emotion](https://github.com/emotion-js/emotion) or even plain CSS.
### Layout Variables
There is a set of CSS Variables available for extensions to use for basic layout needs. They are located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
There is a set of CSS variables available for for basic layout needs. They are located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
```css
--unit: 8px;
@@ -33,7 +31,7 @@ There is a set of CSS Variables available for extensions to use for basic layout
--border-radius: 3px;
```
They are intended to set consistent margins and paddings across components, e.g.
These variables are intended to set consistent margins and paddings across components. For example:
```css
.status {
@@ -44,18 +42,18 @@ They are intended to set consistent margins and paddings across components, e.g.
## Themes
Lens is using two built-in themes defined in [the themes directory](https://github.com/lensapp/lens/tree/master/src/renderer/themes), one for light, and one for dark color schemes.
Lens uses two built-in themes defined in [the themes directory](https://github.com/lensapp/lens/tree/master/src/renderer/themes) – one light and one dark.
### Theme Variables
When Lens is loaded, it transforms the selected theme `json` file into a list of [CSS Custom Properties (CSS Variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) which then gets injected into the `:root` element so any of the down-level components can use them.
When Lens is loaded, it transforms the selected theme's `json` file into a list of [CSS Custom Properties (CSS Variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). This list then gets injected into the `:root` element so that any of the down-level components can use them.
![CSS vars listed in devtools](images/css-vars-in-devtools.png)
When the user changes the theme, the process is repeated, and new CSS Variables appear instead of previous ones.
When the user changes the theme, the above process is repeated, and new CSS variables appear, replacing the previous ones.
If you want to follow a selected theme to keep the 'native' Lens look and feel, respecting the light/dark appearance of your extension, you can use the provided variables and built-in Lens components such as `Button`, `Select`, `Table`, etc.
If you want to preserve Lens's native look and feel, with respect to the lightness or darkness of your extension, you can use the provided variables and built-in Lens components such as `Button`, `Select`, `Table`, and so on.
There is a set of CSS Variables available for extensions to use for theming. They are all located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
There is a set of CSS variables available for extensions to use for theming. They are all located inside `:root` and are defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss):
```css
--font-main: 'Roboto', 'Helvetica', 'Arial', sans-serif;
@@ -90,7 +88,7 @@ as well as in [the theme modules](https://github.com/lensapp/lens/tree/master/sr
...
```
They can be used in form of `var(--magenta)`, e.g.
These variables can be used in the following form: `var(--magenta)`. For example:
```css
.status {
@@ -99,14 +97,14 @@ They can be used in form of `var(--magenta)`, e.g.
}
```
A complete list of all themable colors can be found in the [color reference](../color-reference).
A complete list of themable colors can be found in the [Color Reference](../color-reference).
### Theme Switching
When the light theme is active, the `<body>` element gets a "theme-light" class, `<body class="theme-light">`. If the class isn't there, assume the theme is dark. The active theme can be changed in the `Preferences` page:
When the light theme is active, the `<body>` element gets a "theme-light" class, or: `<body class="theme-light">`. If the class isn't there, the theme defaults to dark. The active theme can be changed in the **Preferences** page:
![Color Theme](images/theme-selector.png)
Currently, there is no prescribed way of detecting changes to the theme in JavaScript. [This issue](https://github.com/lensapp/lens/issues/1336) hopes to improve on this. In the meantime, you can use a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to observe the `<body>` element's `class` attribute to see if the "theme-light" class gets added to it:
Currently, there is no prescribed way of detecting changes to the theme in JavaScript. [This issue](https://github.com/lensapp/lens/issues/1336) has been raised to resolve this problem. In the meantime, you can use a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) in order to observe the `<body>` element's `class` attribute in order to see if the "theme-light" class gets added to it:
```javascript
...
@@ -137,9 +135,9 @@ Currently, there is no prescribed way of detecting changes to the theme in JavaS
## Injected Styles
Every extension is affected by list of default global styles defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss). These are basic browser resets and element styles like setting the `box-sizing` property for every element, default text and background colors, default font sizes, basic heading formatting, etc.
Every extension is affected by the list of default global styles defined in [app.scss](https://github.com/lensapp/lens/blob/master/src/renderer/components/app.scss). These are basic browser resets and element styles, including setting the `box-sizing` property for every element, default text and background colors, default font sizes, basic heading formatting, and so on.
Extension may overwrite these if needed. They have low CSS specificity, so overriding them should be fairly easy.
Extensions may overwrite these defaults if needed. They have low CSS specificity, so overriding them should be fairly easy.
## CSS-in-JS
docs/extensions/testing-and-publishing/testing.md
+12 -6
View File
@@ -2,29 +2,35 @@
## Console.log
`console.log()` might be handy for extension developers to prints out info/errors from extensions. To use `console.log`, note that Lens is based on Electron. Electron has two types of processes: [Main and Renderer](https://www.electronjs.org/docs/tutorial/quick-start#main-and-renderer-processes).
Extension developers might find `console.log()` useful for printing out information and errors from extensions. To use `console.log()`, note that Lens is based on Electron, and that Electron has two types of processes: [Main and Renderer](https://www.electronjs.org/docs/tutorial/quick-start#main-and-renderer-processes).
### Renderer Process Logs
`console.log()` in Renderer process is printed in the Console in Developer Tools (View > Toggle Developer Tools).
In the Renderer process, `console.log()` is printed in the Console in Developer Tools (**View** > **Toggle Developer Tools**).
### Main Process Logs
To view the logs from the main process is a bit trickier, since you cannot open developer tools for them. On MacOSX, one way is to run Lens from the terminal.
Viewing the logs from the Main process is a little trickier, since they cannot be printed using Developer Tools.
#### macOS
On macOS, view the Main process logs by running Lens from the terminal:
```bash
/Applications/Lens.app/Contents/MacOS/Lens
```
You can alos use [Console.app](https://support.apple.com/en-gb/guide/console/welcome/mac) to view logs from Lens.
You can also use [Console.app](https://support.apple.com/en-gb/guide/console/welcome/mac) to view the Main process logs.
On linux, you can get PID of Lens first
#### Linux
On Linux, you can access the Main process logs using the Lens PID. First get the PID:
```bash
ps aux | grep Lens | grep -v grep
```
And get logs by the PID
Then get the Main process logs using the PID:
```bash
tail -f /proc/[pid]/fd/1 # stdout (console.log)