elyra-ai#1768 Improve format of mkdocs version of Elyra Canvas Help (e…

…lyra-ai#1769)

.github/workflows/deploy-docs.yml

@@ -27,17 +27,20 @@ permissions:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-diretory: ./docs
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material 
-      - run: mkdocs gh-deploy --force
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

README.md

@@ -19,11 +19,11 @@ limitations under the License.
 ## elyra/canvas
 
 ## Overview
-The Common Canvas tooling consists of two Node JS modules:
+The Elyra Canvas tooling consists of two Node JS modules:
 
 1) A `Common Canvas` for use in building canvas-like applications. See [detailed API and event documentation](https://github.com/elyra-ai/canvas/tree/main/canvas_modules/common-canvas).
 
-2) `Test harness`  
+2) `Test harness`
 See [here](https://github.com/elyra-ai/canvas/tree/main/canvas_modules/harness) for setting up local environment
 
 ## Documentation
@@ -33,18 +33,21 @@ See [here](https://github.com/elyra-ai/canvas/tree/main/canvas_modules/harness)
 ## Using local version of common-canvas and/or common-properties
 Clone elyra/canvas
 ```sh
+# Clone the repo
 git clone [email protected]:elyra-ai/canvas.git
-# install global libraries for building
+
+# Install global libraries for building
 npm install -g grunt-cli sass
+
 # Build common-canvas and common-properties
 ./<elyra/canvas>/canvas_modules/common-canvas/build.sh
 ```
-In your application's package.json replace  
+In your application's package.json replace
 ```
 "@elyra/canvas": "<version>"
 ```
 with
-```  
+```
 "@elyra/canvas": "file:<elyra/canvas>/canvas_modules/common-canvas"
 ```
 
@@ -57,7 +60,8 @@ npm install
 
 ### Contribute to the Elyra Canvas documentation (mkdocs)
 1. Python v3 needs to be available.
-2. Go to canvas directory.
+
+2. Go to canvas/docs directory.
 
 3. Install required mkdocs packages using pip3.
 ```

docs/mkdocs.yml

@@ -0,0 +1,121 @@
+#
+# Copyright 2017-2023 Elyra Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+site_name: Elyra Canvas
+repo_url: https://github.com/elyra-ai/canvas
+docs_dir: pages
+
+theme:
+    name: material
+    highlightjs: true
+    logo: assets/FlowIcon.png
+    favicon: assets/FlowIcon.png
+    palette:
+        scheme: default
+    features:
+      - content.code.copy
+      - content.action.edit
+      - navigation.tabs
+      - navigation.indexes
+
+plugins:
+    - search
+
+extra_css:
+  - css/styles.css
+
+extra_javascript:
+  - js/links-in-new-tabs.js
+
+edit_uri: edit/main/docs/
+
+# Documentation and theme
+copyright: 'Copyright  © 2024 Elyra Authors, an open source project and all are welcome to contribute! Maintained by the Elyra Authors Team'
+
+nav:
+  - Home: index.md
+
+  - Installation:
+    - 01-install/index.md
+
+  - Common Canvas:
+    - 02-canvas/index.md
+    - Canvas Components:
+      - 02-canvas/01-components/index.md
+      - Flow Editor:
+        - 02-canvas/01-components/01-editor/index.md
+        - Nodes: 02-canvas/01-components/01-editor/01-Nodes.md
+        - Links: 02-canvas/01-components/01-editor/02-Links.md
+        - Comments: 02-canvas/01-components/01-editor/03-Comments.md
+      - Palette: 02-canvas/01-components/02-Palette.md
+      - Context Menu: 02-canvas/01-components/03-Context-Menu.md
+      - Context Toolbar: 02-canvas/01-components/04-Context-Toolbar.md
+    - Config Objects:
+      - 02-canvas/02-configs/index.md
+      - Canvas Config: 02-canvas/02-configs/01-canvas-config.md
+      - Toolbar Config: 02-canvas/02-configs/02-toolbar-config.md
+      - Notification Config: 02-canvas/02-configs/03-notification-config.md
+      - Context Menu Config: 02-canvas/02-configs/04-context-menu-config.md
+      - Keyboard Config: 02-canvas/02-configs/05-keyboard-config.md
+    - Callbacks: 02-canvas/03-callbacks/index.md
+    - Canvas Controller:
+      - 02-canvas/04-controller/index.md
+      - Styling Canvas Objects: 02-canvas/04-controller/01-Styling-Objects.md
+      - Decorations: 02-canvas/04-controller/02-Decorations.md
+      - API Object Structure: 02-canvas/04-controller/03-Object-structure-used-by-API.md
+      - Notification Message Specification: 02-canvas/04-controller/04-Notification-Message-Specification.md
+      - Programmatically Creating New Canvas Nodes: 02-canvas/04-controller/05-Programmatically-creating-new-canvas-nodes.md
+      - Read Only or Locked Canvas: 02-canvas/04-controller/06-Read-only-or-locked-canvas.md
+      - Calling the Canvas Controller API: 02-canvas/04-controller/07-Calling-the-Canvas-Controller-API.md
+    - Node Creation from External Object: 02-canvas/05-ext-objs/index.md
+    - Commmand Stack API: 02-canvas/06-stack/01-Command-Stack.md
+    - Customizing Node Layout Properties: 02-canvas/07-layout/01-Customizing-Node-Layout.md
+    - Context Menu Wrapper Documentation: 02-canvas/08-menu/01-Context-Menu-Wrapper.md
+    - External Subflows Support: 02-canvas/09-ext-flows/01-External-Subflows-support.md
+    - Flow Validation API: 02-canvas/10-validate/01-Flow-Validation-API.md
+
+  - Common Properties:
+    - 03-props/index.md
+    - Parameter Definitions: 03-props/01-Parameter-Definition.md
+    - UI Hints: 03-props/02-UI-Hints.md
+    - Controls: 03-props/03-Controls.md
+    - Conditions: 03-props/04-Conditions.md
+    - Custom Components: 03-props/05-Custom-Components.md
+    - Properties Controller: 03-props/06-Properties-Controller.md
+
+  - Troubleshooting:
+    - 04-trouble/01-Troubleshooting.md
+
+  - Contributing:
+    - 05-contrib/01-Testing-Guidelines-for-Development.md
+
+  # - Testing Guidelines for Development: 5.0-Testing-Guidelines-for-Development.md
+
+markdown_extensions:
+  - admonition:
+  - codehilite:
+  - extra:
+  - pymdownx.magiclink:
+  - pymdownx.inlinehilite:
+  - pymdownx.highlight:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - sane_lists:
+  - smarty:
+  - toc:
+      permalink: True

docs/index.md → docs/pages/01-install/index.md

@@ -1,14 +1,4 @@
-# Welcome to the Elyra Canvas Documentation
-
-The elyra-ai/canvas repo contains three main components:
-
-* [Common Canvas](2.0-Common-Canvas-Documentation.md) - This contains canvas functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed on the NPM registry. It provides a way for an application to display a flow of data operations (shown as a set of nodes connected with links) defined in a pipeline flow JSON document, to the user and to allows the user to interact with the display to modify the flow. Common canvas is a react component which can be imported, and is assisted by a regular JavaScript class called `CanvasController` which provides an API and handles the internal data model of the flow. Common canvas is highly customizable where node shape and appearance, colors, styles layout etc can all be customized by your application code.
-
-* [Common Properties](3.0-Common-Properties-documentation.md) - This contains properties functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed on the NPM registry. It provides a way to translate a JSON document, which describes a set of properties with UI hints, into working properties dialog panel. Common properties is a react component and has an associated properties controller object. 
-
-* [Test Harness](https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness#test-harness) - This provides a node.js app which displays a UI which allows you to try out various features of the common canvas and common properties components. Bear in mind this is not supposed to be a fully functional app but is, as the name suggests, a framework for testing. To get select one of the sample applications or select `None` as the sample app and then select a test canvas file from the `Canvas Diagram` drop down list and a test palette from the `Canvas palette` drop down list.
-
-## Installation
+# Installation
 
 You'll need to build your application with Elyra Canvas.
 
@@ -72,19 +62,56 @@ render() {
 }
 ```
 
-## Notes
-When building your application you will need to load fonts and override styles can be found here:
-[Styling](4.0-Styling.md)
+## Overriding Styles and Color Themes
+
+When building your application you will need to load fonts and override styles:
+
+### CSS styling for quick start
+
+
+If you just want to get up and running and don't care about scss then import these regular css files:
+
+  - carbon-components/css/carbon-components.min.css
+  - @elyra/canvas/dist/styles/common-canvas.min.css
+    - version 8.x and older @elyra/canvas/dist/common-canvas.min.css
+
+More information about carbon components can be found here http://www.carbondesignsystem.com/getting-started/developers
+
+
+### SCSS styling (recommended)
+
+If you want to use the full power of scss styling with variable overrides etc then include these imports in your main scss file:
+```sass
+@import "carbon-components/scss/globals/scss/styles";
+@import "@elyra/canvas/src/index.scss";
+```
 
-## Testing
-When testing your application with Jest, this error might show up: `crypto.getRandomValues() not supported`. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported for details. 
+  - use `autoprefixer` when building
+  - if using webpack under the `sass-loader` and make sure to include
 
-To fix, added this to your jest setup file:
 ```js
-const cryptoJest = require("crypto");
-Object.defineProperty(global.self, "crypto", {
-	value: {
-		getRandomValues: (arr) => cryptoJest.randomBytes(arr.length)
-	}
-});
+options: { includePaths: ["node_modules"] }
 ```
+
+Again, you can refer to the test harness [index.scss file](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/styles/index.scss) for sample code.
+
+
+### Loading Fonts
+You may find that there is a pause in common canvas behavior, such as when the context menu is first displayed, which is caused by fonts being loaded. This can be fixed by adding the following to the `.scss` file for your application:
+```
+$font-path: "/fonts";
+@import "carbon-components/scss/globals/scss/styles";
+```
+The fonts will need to be imported from carbon before carbon styles and placed in a public `/fonts` directory.
+You can see an example of this in the common-canvas test harness (which is the equivalent of a host application) in this repo. That is, the [index.scss file](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/styles/index.scss) contains the lines above and the grunt build files ensures the fonts are copied from`node_modules/carbon-components/src/globals/` to the `<carbon fonts folder>` directory.
+
+
+### 3rd party styling
+
+If you are using common-properties then also include the react-virtualized styles:
+  - react-virtualized/styles.css
+
+
+
+
+

docs/pages/02-canvas/01-components/01-editor/01-Nodes.md

@@ -0,0 +1,10 @@
+# Nodes
+
+## Introduction
+
+Nodes displayed in the flow editor can represent data operations or other types of
+operations for the type of flow the application displays.
+
+Nodes are made up of a number of display elements such as an image, label background shape etc.
+
+[Under construction]

docs/pages/02-canvas/01-components/01-editor/03-Comments.md

@@ -0,0 +1,5 @@
+# Comments
+
+## Introduction
+
+[Under construction]

docs/pages/02-canvas/01-components/01-editor/index.md

@@ -0,0 +1,13 @@
+# Flow Editor
+
+The Flow Editor displays the flow to the user and allows the user to interact with the flow using the mouse/trackpad and the keyboard and other input devices.
+
+The editor displays the following object types which the user can interact with:
+
+* Nodes
+* Links
+* Comments
+* The Canvas background
+
+
+[Still under construction]