Version 0.1.10 Documentation Update

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 0.1.10
+
+- Added more [welcome content](https://code.visualstudio.com/api/extension-guides/tree-view#welcome-content) in outlines panes that have not yet opened a tree for starting a server, connecting to it, and added content to help with automation settings.
+- Changed the starting default configuration setting for starting and connecting to the leoBridge server script to false.
+- Made starting and connecting to the leoBridge server script easier to access in the interface, and in the welcome/settings webview.
+- Added new CONTRIBUTING.md markdown file for running the development version of the leoInteg extension.
+- Closes [#44](https://github.com/boltex/leointeg/issues/44)
+
 ## 0.1.9
 
 - Added new compilation configuration (server, extension, or both) to help debugging.

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# How to install and run the development version
+
+Thanks for trying out the development version of LeoInteg! :sunglasses: Contributions and pull requests are more than welcome!
+
+## Introduction
+
+If you're new to vscode and want to try out Leo with this vscode extension, you might want to look at this [Getting Started](https://code.visualstudio.com/docs#vscode-in-action) page to get an overview.
+
+Furthermore, if you've never ran a vscode extension in an **Extension Development Host**, here is a [short overview about running and modifying a simple extension](https://code.visualstudio.com/api/get-started/your-first-extension).
+
+If you're having problems with the procedures below, try [running this sample extension](https://github.com/Microsoft/vscode-extension-samples/tree/master/helloworld-sample#running-the-sample) first to catch underlying problems or missing dependencies.
+
+## Development requirements
+
+- Make sure you have Node.js and Git installed.
+
+- Check your node.js version by typing `node -v` in a terminal. [The latest lts version is 12.18.0](https://nodejs.org/en/download/).
+
+- Also check your vscode version by opening the 'about' dialog from the help menu. You should at least match or exceed the version below.
+
+On Windows:
+
+![about](resources/vscode-about-win.png)
+
+On Linux:
+
+![about](resources/vscode-about.png)
+
+## Getting the source and its development dependencies
+
+- Clone the repository using the command line by typing : `git clone https://github.com/boltex/leointeg.git`
+
+![clone](resources/git-clone.png)
+
+- Although you could 'cd' into the leoInteg folder and run some commands from the same terminal, let's instead use the terminal from within vscode. So open the leoInteg folder with vscode instead:
+
+![open with vscode](resources/open-with-vscode.png)
+
+- With vscode now opened with the **leoInteg folder as its workspace**, use the `ctrl+shift+p` keyboard shortcut to open command palette and toggle the terminal. (You can find any command through the command palette)
+
+![open terminal](resources/open-terminal.png)
+
+- Install the development dependencies by entering the `npm install` command in the terminal. **(Important if you also just _pulled_ updated sources)**
+
+- When the command has finished running, you should see logged results in the terminal and also that a new **node_modules** folder was created.
+
+![dependencies](resources/node-modules.png)
+
+- You're now ready to **compile and run** the development version of the leoInteg extension.
+
+## Choosing a debug profile
+
+- Bring up the **Run view**, by selecting the Run icon in the **Activity Bar**. _(Screenshot below)_
+
+- When simply running the extension, choose the **Run Extension** profile.
+
+![profile](resources/debug-profile.png)
+
+> (**Optional**) To contribute code to the python server script, or run it through the vscode debugger, you may need to install the [python development extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python).
+
+- For simply running and using leoInteg, just start the extension and the server as shown below.
+
+## Starting the extension
+
+- Use the **Start Debugging** command (or press **F5**) to start another vscode window with the expansion _installed and running_ within it.
+
+![extension started](resources/leointeg-started.png)
+
+- If any problems occurred during the extension compilation it will be logged in the vscode instance that started the debug process in its **task-webpack** terminal panel. Otherwise if its running, the extension itself will be logging any messages in the **debug-console** panel. (See animation below)
+
+![extension logs](resources/debug-anim.gif)
+
+## The python server script
+
+- This extension needs the **`leobridgeserver.py`** script to be running. That is where the two extra extension requirements come into play: Having [Leo's path made available in the \$PYTHONPATH environment variable](https://github.com/leo-editor/leo-editor/blob/master/INSTALL.TXT#L126), and having the [Websocket Python Library installed](https://websockets.readthedocs.io/en/stable/intro.html)
+
+### 3 ways to start the server script
+
+1. You can have LeoInteg try to start a server script instance itself via the **Start Leo Bridge Server** command or button. It will use the 'py' command on Windows and 'python3' command on other OSes by default. _You can automate this process via leoInteg's configuration settings._
+2. You can have vscode's **Debug View** start it as a debug session starts by choosing a debug profile that includes the server script. It's then possible to step in, inspect and debug the python server script. _The [python development extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) may be required._
+3. You can also start it yourself manually, by running the leobridgeserver.py script from a command prompt.
+
+### Using Anaconda or other custom python installations
+
+- LeoInteg provides configuration options to specify how to launch python interpreter but this may not be enough to get it to start on your system, see [#10](https://github.com/boltex/leointeg/issues/10) and other issues relating to configurations in _sitecustomize.py_ file as noted in [Leo's google group forum](https://groups.google.com/d/msg/leo-editor/FAP8lVnWLyQ/lWHWEYH9AgAJ).
+
+- If Leointeg or vscode cannot start running the server script on you system or OS, a **workaround** is to start the server script beforehand manually with whichever python interpreter you have installed.
+
+![launch server](resources/manual-server-start.png)
+
+- It will terminate automatically when a user disconnect.
+
+**Note**: If force-closing the server from the integrated vscode terminal, use the 'Kill terminal' button instead of the 'X' that just hides the panel.
+
+![kill terminal](resources/kill-terminal.png)
+
+## Issues
+
+More information can be found on the repository's [Issues Page](https://github.com/boltex/leointeg/issues), where details and troubleshooting can be addressed more directly.

README.md

@@ -4,9 +4,10 @@
 
 ### Break your code down into sections structured as an outline, to derive or parse back your files
 
-Leo is a fundamentally different way of using and organizing data, programs and scripts.\
+> Leo is a fundamentally different way of using and organizing data, programs and scripts.
+
 See Leo, the Literate Editor with Outline, at [leoeditor.com](https://leoeditor.com/)
-or on [github](https://github.com/leo-editor/leo-editor).
+or on [github](https://github.com/leo-editor/leo-editor), and vscode at [code.visualstudio.com](https://code.visualstudio.com/).
 
 ![Screenshot](resources/animated-screenshot.gif)
 
@@ -21,40 +22,31 @@ or on [github](https://github.com/leo-editor/leo-editor).
 
 ## Development version installation
 
-As you can see from this simple
-['Hello-world' expansion example](https://github.com/Microsoft/vscode-extension-samples/tree/master/helloworld-sample#running-the-sample),
-cloning and running an expansion from source is quite easy:
-
-Make sure you have Node.js and Git installed, then:
+In addition to the above requirements, make sure you have Node.js and Git installed, then clone the sources and run `npm install` in a terminal to install the remaining development dependencies.
 
-1. Get this repository: `git clone https://github.com/boltex/leointeg.git`
-2. Right-click it -> open with vscode (or from a vscode window, File-> Open Folder...)
-3. Run `npm install` in terminal before the first run to install dependencies.
-4. _(Optional)_ Open vscode's 'Run/Debug' panel to choose a debugging profile (extension, server, or both)
-5. Press F5 to run the extension in its own vscode debug instance. (It will try to start its own server by default)
+![run extension](/resources/run-extension.png)
 
-After compiling, a new vscode window will be running with leoInteg.
+You can then run the **Run Extension** target, as shown above, in the **Debug View**.
 
-The plugin will be activated if the workspace of this new window contains a leo file,
-it can also be manually activated by going to the Leo view in the activity bar.
-
-Once activated, it will start a bridge and connect to it automatically by default.
-The 'Open Leo File' button will then be available.
+> See [CONTRIBUTING.md](CONTRIBUTING.md) for complete details on how to install and run this extension.
 
 ## Features
 
-- A Leo Outline in the explorer view, or in its own panel via the activity bar.
-- A welcome screen that also provides access to the configuration settings.
-- Derived files change detection.\
-  (Set the **'Force reload or ignore changes'** option to **'Reload All'** to automate synchronization)
-- Access Leo commands with context menus, outline-node hover icons, keyboard shortcuts, or the command palette:
+- A **Leo Outline** in the explorer view, or as a standalone sidebar, **body panes** and **Log Window**.
+- A **welcome screen** that also gives access to this extension's **settings**.
+- **Derived files change detection**. See [External Files](#derive-external-files) below for more details
+- Access **Leo commands** with context menus, outline-node hover icons, keyboard shortcuts, or the command palette:
   - Open body panes to the side
   - Outline edition commands
   - Clipboard operations
   - Undo/Redo commands
 
 ![Menu](resources/context-hover-menus.png)
 
+## Keybindings
+
+> _More commands are available by opening the **Command Palette** and typing 'Leo'_
+
 | Keybinding                 |     |                       | Command            |
 | :------------------------- | :-- | :-------------------- | :----------------- |
 | `Alt + -`                  |     |                       | Contract All       |
@@ -72,7 +64,21 @@ The 'Open Leo File' button will then be available.
 | `Ctrl + L`                 | or  | `Shift + Alt + Left`  | Move Outline Left  |
 | `Ctrl + R`                 | or  | `Shift + Alt + Right` | Move Outline Right |
 
-### _Status Bar Indicator_
+## Derive External Files
+
+Use the **Save Leo File** command to derive external files.
+
+Leo will detect derived file changes and will ask to either **refresh from disk** or **ignore the changes**.
+
+![derive files](resources/derived-file.gif)
+
+## Automate Synchronization
+
+The **change detection** process can be automated to always refresh, or ignore file changes: A **notification** will inform you of the action taken instead.
+
+![auto sync](resources/auto-sync.gif)
+
+## Status Bar Indicator
 
 A customizable keyboard status bar indicator is shown when this extension is activated.
 It will turn orange (or your choice of text and color), when leo's **keyboard shortcuts** are active.
@@ -82,7 +88,9 @@ This occurs when an outline node or a body pane has focus:
 
 ## Extension Settings
 
-### _Open the command palette and start typing_ `leo settings`
+### Open the command palette `CTRL+SHIFT+P` and start typing `leo settings` to access LeoInteg's welcome/settings screen
+
+> _(Changes are auto-saved to the user's profile after 0.5 seconds)_
 
 - Control the visibility of the outline pane in the explorer view.
 - Decide how and when to refresh and synchronize content when derived (external) file are modified.
@@ -95,11 +103,13 @@ This occurs when an outline node or a body pane has focus:
 
 ## Issues
 
+Main issues are listed below. See the repository's [Issues Page](https://github.com/boltex/leointeg/issues) to submit issues.
+
 ### Linux Keybindings
 
 If you're experiencing trouble with the keyboard shortcuts for
 the 'Clone Node' or the 'Promote' and 'Demote' commands,
-use **"keyboard.dispatch": "keyCode"** in your settings and restart VS Code.
+use **"keyboard.dispatch": "keyCode"** in your settings and restart vscode.
 See [Troubleshoot Linux Keybindings](https://github.com/microsoft/vscode/wiki/Keybinding-Issues#troubleshoot-linux-keybindings) for more information.
 
 ### Move outline keyboard commands
@@ -109,13 +119,14 @@ To help with this conflict, outline-move keyboard commands will only trigger
 with the additional condition of having no text selection in the editor.
 So select at least one character to use the previously assigned **`Ctrl+D`** command in body panes.
 
+> This extension is still in development, so please refer to its [issue tracker for known issues](https://github.com/boltex/leointeg/issues), and please contribute with additional information if you encounter other issues yourself.
+
 ## Intended Features
 
 - Support for multiple simultaneous opened Leo files.
-- Support multiple connections to the leoBridge server, allowing multi-user live edition of the same Leo file.
+- Support multiple connections to the leoBridge server.
 - Syntax-highlighting for body panes that matches Leo's syntax-highlighting.
-- Finding and 'go-to' specific line(s) from derived files in outline nodes (For error lookup, breakpoints, etc.)
-- Optionally display line numbers in relation to derived files instead of the standard editor line numbering when applicable.
+- Display line numbers in relation to derived files, along with 'go-to' specific line functionality for error lookups and breakpoints.
 
 ## How it works