Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Editors (reST)

From TYPO3Wiki
Jump to: navigation, search

Since reST is meant to be readable by "design", a basic editor is enough to start writing documentation. However, there are editors offering facilities towards reST support such as syntax highlighting, conversion to HTML on the fly, ...

Wanted features

Basically any text editor will do. However, more comfortable would be to use an editor with some advanced functions, e.g. one, which can reformat linebreaks in paragraphs easily (automatically).

  • Most important feature: "Column Selection Mode". Is a K.O. criterium. (Exact number of spaces/tabs is important for reST markup to work; one space too much/not enough and it breaks.)
  • Function to replace tabs by spaces
  • Un/indent marked lines by shift/tab
  • Ability to join/split lines automatically: Difference between hard wrap and soft wrap: A hard wrap inserts actual line breaks in the text at wrap points. With soft wrapping the actual text is still on the same line but looks like it's divided into several lines.

Online Editor

Notex.ch

An unbelievable ReST editor is https://notex.ch/.

It can handle complete projects. You can upload your files and edit stuff. If you are unsure about the exact rendering, you can always export your content as PDF or HTML to see the actual result.

Source: https://github.com/hsk81/notex

ninjs.org

An online editor is available at http://rst.ninjs.org/.

It converts your rst syntax to HTML on the fly.

It does not support all reST constructs (like the ".. codeblock::" directive), but all in all it is a great help to see, if your reST syntax is valid. Should it be not, the page shows you a helpful error message.

Technical details about this editor.

EXT:sphinx

The TYPO3 sphinx extension https://extensions.typo3.org/extension/sphinx/ provides a full-fledged editor integrating a project browser (to quickly edit any file in your documentation project) and a reference browser to easily cross-link to other extension manuals or official documents (TYPO3 API, Security Guide, ...).

It lets you browser your documentation, and switch to "edit mode" from any chapter. When you save and close, the documentation is automatically re-rendered so that you see your changes "on-the-fly".

This extension comes with a tool to kickstart a documentation project (either for in-house documents or for one of your extensions) and another tool to convert your existing OpenOffice manual to Sphinx/reStructuredText.

Open source (= free of cost)

Software Remark Platform License
UliPad Ulipad is a wxPython powered, programmer oriented and flexible editor.

Text convertion and view -- python -> html, reStructured Text -> html, textile -> html, and you can output or view the html text in message window, or html view window, or replace the selected text.

Windows, Mac GNU GPL v2
Notepad++ is at least a start.

You might want to have a plugin for easy reformatting of line breaks (alternatively live with hard line breaks at some places and use the feature "automatical linebreaks" to adjust the text to the width of your window).

Windows GPL
ReText Syntax highlighting + convert to HTML as typing Linux GPL v2
Editra It seems capable of almost all what we would need right out of the box. I'm missing only one thing: automatically rewrap a long line to a bunch of small lines. Linux, Mac and Windows
... ... ... ...

Non-free programmes

Software Remark Platform License
PyCharm Is the Python sibling of PhpStorm, also by JetBrains.

Has rst syntax highlighting Has soft line wrapping that adapts itself to the screen (= to the width of the window)

Mac, Linux, Windows Commercial
Sublime Text Syntax highlighting Mac, Linux, Windows Commercial
TextMate Mac Commercial
... ... ... ...

Further reading

If you think you have spotted a gem, don't hesitate to report your editor into the table!

Besides that, refer to this reading to get a more in depth overview of the existing "players" on the market.