Tools for Editing reST

We will cover some IDEs here, that may be useful if you edit locally with the Workflow #2: "Local editing and rendering with Docker".

When editing reST files locally, you should use an editor or IDE with good support for syntax highlighting and marking errors in reST.

• PhpStorm is commonly used by developers in the TYPO3 community. It does however cost money. PhpStorm comes with a number of plugins for TYPO3, for example for TypoScript and Fluid.

• Visual Studio Code also comes with plugins for TYPO3 and for reStructuredText. And it is free.

Other alternatives can be found in the "Free Editors" section of StackOverflow: reStructuredText tool support.

The editor or IDE should ideally have the following features:

• syntax highlighting for reST

• show syntax errors

• provide possibility to use (configurable) code snippets for easy insertion of directives

• provide keyboard shortcuts and configurable commands for running Docker

• built in spell checking (English)

Setup your editor / IDE to use the .editorconfig file, which already exists in most documentation repositories. This will set up your editor / IDE to comply with our basic coding guidelines.

You may have to install an additional plugin, see EditorConfig.

Visual Studio Code

restructuredText Plugin

1. Open Extensions (CTRL+SHIFT+X)

2. Enter reStructuredText in search box

3. Select LeXtudio extension

4. Press install

The LeXtudio extension comes with some built in code snippets.

You can:

• show all snippets by pressing CTRL+Space

• start entering the beginning of a snippet name and press tab

Tip

Try this now by typing image and then TAB.

You can easily extend the snippets by adding user snippets:

1. Open File > Preferences > User Snippets

2. Enter a name

3. Edit the json file

Here is an example:

{
   "image (full)": {
      "prefix": "imgf",
      "body": [
         ".. image:: $1",
         "   :class: with-shadow",
         "   :alt: $2",
         "   :target: $3",
         "$4"
      ],
      "description": "image with parameters"
   }
}

• You can enter the snippet by typing imgf and then TAB

• The $1, $2 etc. mark the places where further TABs will take you. Use this if extra text needs to be entered

PhpStorm

reStructuredText Plugin

You should activate the reStructuredText plugin that will assist you when editing reST files. In order to activate a plugin, press ctrl + alt + s, then select Plugins, search for the plugin and enable it (mark checkbox).

If the Plugin is not installed yet, you may have to Browse repositories, select the plugin and click the green Install button.

Some errors in formatting will be pointed out:

EditorConfig Plugin

Additionally, (download) and enable the EditorConfig plugin in order to get correct Coding Guideline settings like indent width already defined in .editorconfig file of documentation project.

Spellchecking

You can add some specific TYPO3 spellings to PhpStorms internal dictionary. Just place the cursor on the word, click alt-enter and then "Save to dictionary".

For more information, see the Spellchecking PhpStorm page.