Editor

The following page outlines guides for recommended editors and integrated development environments (IDEs) for OSE workbench development.

Visual Studio Code

Visual Studio Code is a free, cross-platform, extensible editor built on open-source.

Recommended Extensions

Extension	Description
Python	Python language support
Python Test Explorer for Visual Studio Code	Run your Python Unittest or Pytest tests with the Test Explorer UI.
Python Docstring Generator	Quickly generate docstrings for python functions.

The above extensions should be listed in .vscode/extensions.json within each workbench repository to prompt the user to install them. See Workspace recommended extensions for additional information.

Recommended Extensions Configuration

OSE Workbench Platform includes an editor-config command configuring the above VS Code extensions with the recommended configuration.

See the editor-config command documentation in the README for additional information.

OSE Workbench Platform includes an `editor-config` command for outputting recommended VS Code configuration.

```
$ osewb editor-config -h ↵
usage: osewb editor-config

optional arguments:
  -h, --help            show this help message and exit
  -m, --merge-workspace-settings
                        Merge VS Code workspace settings.
  -o, --overwrite-workspace-settings
                        Overwrite VS Code workspace settings.
```

Simply running `osewb editor-config` will output the recommended VS Code configuration settings which user's can copy-paste into their VS Code user settings, or workspace settings, `settings.json` file(s). See [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) for additional information.

The `-m` or `--merge-workspace-settings` flag will merge the current VS workspace settings into the platform's recommended settings. The platform's settings will win any collisions or merge conflicts.

The `-o` or `--overwrite-workspace-settings` flag will overwrite the current VS Code workspace settings with either the minimal-set of recommended configuration or merged settings depending upon the presence of the `-m` flag. Before overwriting, users will see a preview of the settings and must confirm overwriting in a yes or no CLI prompt.

Python Docstring Generator Configuration

A custom docstring template for OSE workbenches has been included in ose-workbench-platform/osewb/.mustache.

{{! Sphinx Docstring Template }}
{{! For VSCode Python Docstring Generator Extension }}
{{! https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring }}
{{! Modified to remove typePlaceholder }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{var}}: {{descriptionPlaceholder}}
{{/kwargs}}
{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{#returns}}
:return: {{descriptionPlaceholder}}
{{/returns}}
{{#yields}}
:yield: {{descriptionPlaceholder}}
{{/yields}}

You should configure the extension to use this template in order to avoid adding types to your docstrings.

Types in docstrings are redundant with Type Hints — the preferred way to document the types in Python.

Is VS Code open-source?

Explained by a VS Code developer:

When we set out to open source our code base, we looked for common practices to emulate for our scenario. We wanted to deliver a Microsoft branded product, built on top of an open source code base that the community could explore and contribute to.

We observed a number of branded products being released under a custom product license, while making the underlying source code available to the community under an open source license. For example, Chrome is built on Chromium, the Oracle JDK is built from OpenJDK […] Those branded products come with their own custom license terms, but are built on top of a code base that’s been open sourced.

We then follow a similar model for Visual Studio Code. We build on top of the vscode code base we just open sourced and we release it under a standard, pre-release Microsoft license.

VSCodium

For open-source purists, you may be interested in the MIT-licensed VSCodium as a VS Code alternative.

Don’t See Your Preferred Editor?

We need you to help write the guide! 🙂