ReST Editor - Eclipse Demo Camp Grenoble 2011

reStructuredTextReST EditorQuestions ?

ReST Editor

Thomas CalmantisandlaTech

Thomas Calmant isandlaTech ReST Editor

Outline

1 reStructuredTextA documentation languageSample codeHow to provide documents ?Compilation processKnown usersExisting editors

2 ReST EditorreStructuredText edition in EclipseOpen source plug-inThe Run configurationA word about wrapping


A documentation languageSample codeHow to provide documents ?Compilation processKnown usersExisting editors

A documentation language

Designed for Python documentation (code and references)

Defined at docutils.sourceforge.net by David Goodger

Plain text mark-up language

Easy to read / write without specific tools

Compilable into many output formats (HTML, LaTex, CHM, man,QtDoc, ...)








































Sample code

How to provide documents ?==========================

With |rest| :

.. image:: _static/workflow-rst.png:align: center:height: 3cm

* One source format

* Can be an aggregation of multiple .rst files

* Plain text, so complete version controlcan be done with Git, Subversion, ...




How to provide documents ?

The old way :

Time wasting

Possible update errors

May need to have the document in different source formats

Nearly impossible to have a correct version control





The old way :

Time wasting








The old way :

Time wasting








The old way :

Time wasting








With reStructuredText :

One source format

Can be an aggregation of multiple .rst filesPlain text, so complete version control can be done with Git,Subversion, ...Compiled with the same tool for major outputs : Sphinx






One source formatCan be an aggregation of multiple .rst files

Plain text, so complete version control can be done with Git,Subversion, ...Compiled with the same tool for major outputs : Sphinx






One source formatCan be an aggregation of multiple .rst filesPlain text, so complete version control can be done with Git,Subversion, ...

Compiled with the same tool for major outputs : Sphinx






One source formatCan be an aggregation of multiple .rst filesPlain text, so complete version control can be done with Git,Subversion, ...Compiled with the same tool for major outputs : Sphinx




Compilation process

Sphinx : generates major outputs (HTML, LaTex, man, QtDoc, ...)

Some other tools exist :

rst2pdf : generates PDF without LaTex (uses ReportLab library)rst2beamer : generates a LaTex Beamer presentationrst2odt : generates Open/LibreOffice documentsrst2a : an on-line styled PDF generator

All are based on Python, using the official docutils parser.




Compilation process

Sphinx : generates major outputs (HTML, LaTex, man, QtDoc, ...)Some other tools exist :






Compilation process


rst2pdf : generates PDF without LaTex (uses ReportLab library)

rst2beamer : generates a LaTex Beamer presentationrst2odt : generates Open/LibreOffice documentsrst2a : an on-line styled PDF generator





Compilation process


rst2pdf : generates PDF without LaTex (uses ReportLab library)rst2beamer : generates a LaTex Beamer presentation

rst2odt : generates Open/LibreOffice documentsrst2a : an on-line styled PDF generator





Compilation process


rst2pdf : generates PDF without LaTex (uses ReportLab library)rst2beamer : generates a LaTex Beamer presentationrst2odt : generates Open/LibreOffice documents

rst2a : an on-line styled PDF generator





Compilation process







Compilation process







Known users

Guides & References

PythonBazaarBlenderOpenERPZopeMany others Python and non-Python projects

Books

C/C++ Software Development with Eclipse (on-line book)The repoze.bfg Web Application Framework (printed book)




Known users

Guides & ReferencesPython

BazaarBlenderOpenERPZopeMany others Python and non-Python projects

Books





Known users

Guides & ReferencesPythonBazaar

BlenderOpenERPZopeMany others Python and non-Python projects

Books





Known users

Guides & ReferencesPythonBazaarBlender

OpenERPZopeMany others Python and non-Python projects

Books





Known users

Guides & ReferencesPythonBazaarBlenderOpenERP

ZopeMany others Python and non-Python projects

Books





Known users

Guides & ReferencesPythonBazaarBlenderOpenERPZope

Many others Python and non-Python projects

Books





Known users

Guides & ReferencesPythonBazaarBlenderOpenERPZopeMany others Python and non-Python projects

Books





Known users


Books





Known users


BooksC/C++ Software Development with Eclipse (on-line book)

The repoze.bfg Web Application Framework (printed book)




Known users


BooksC/C++ Software Development with Eclipse (on-line book)The repoze.bfg Web Application Framework (printed book)




Existing editors

Few editors with a real support (vim, emacs, JED, ...)

Often with only a syntax coloration support




Existing editors

Few editors with a real support (vim, emacs, JED, ...)

Often with only a syntax coloration support


Outline

1 reStructuredTextA documentation languageSample codeHow to provide documents ?Compilation processKnown usersExisting editors

2 ReST EditorreStructuredText edition in EclipseOpen source plug-inThe Run configurationA word about wrapping


reStructuredText edition in EclipseOpen source plug-inThe Run configurationA word about wrapping

reStructuredText edition in Eclipse

Syntax coloration

Document hierarchy edition using the Outline view

Directives help on mouse hover

Basic context assistance

A Sphinx/Makefile run configuration

Spell checking with Hunspell4Eclipse





Syntax coloration










Syntax coloration










Syntax coloration










Syntax coloration










Syntax coloration









Open source plug-in

Open source plug-in, hosted at SourceForge.net.

Project site : resteditor.sourceforge.netUpdate site : resteditor.sourceforge.net/eclipseAvailable on the Marketplace

Contributors are welcome !




Open source plug-in

Open source plug-in, hosted at SourceForge.net.Project site : resteditor.sourceforge.net

Update site : resteditor.sourceforge.net/eclipseAvailable on the Marketplace





Open source plug-in

Open source plug-in, hosted at SourceForge.net.Project site : resteditor.sourceforge.netUpdate site : resteditor.sourceforge.net/eclipse

Available on the Marketplace





Open source plug-in

Open source plug-in, hosted at SourceForge.net.Project site : resteditor.sourceforge.netUpdate site : resteditor.sourceforge.net/eclipseAvailable on the Marketplace





Open source plug-in

Open source plug-in, hosted at SourceForge.net.Project site : resteditor.sourceforge.netUpdate site : resteditor.sourceforge.net/eclipseAvailable on the Marketplace





The Run configuration

Needs Python and Sphinx to be installed on the system

Works on Unix-like (Makefile) and Windows (make.bat)Allows to run any MakefileAllows to provide an environment to the command





Needs Python and Sphinx to be installed on the systemWorks on Unix-like (Makefile) and Windows (make.bat)

Allows to run any MakefileAllows to provide an environment to the command





Needs Python and Sphinx to be installed on the systemWorks on Unix-like (Makefile) and Windows (make.bat)Allows to run any Makefile

Allows to provide an environment to the command





Needs Python and Sphinx to be installed on the systemWorks on Unix-like (Makefile) and Windows (make.bat)Allows to run any MakefileAllows to provide an environment to the command




A word about wrapping

No line wrapping support in built-in TextEditor

ReST Editor hard line wrapping inspired from Texlipse method

Modifies the document with an auto-edit strategyDetects blocks of similar lines, then wrap and replace the wholeblock

Soft line wrapping support :

Uses the hard line wrapping, but storing information aboutwrapped blocksUn-wraps blocks on saveProblem : implied modifications on save always set the documentstate to dirty





No line wrapping support in built-in TextEditorReST Editor hard line wrapping inspired from Texlipse method









Modifies the document with an auto-edit strategy

Detects blocks of similar lines, then wrap and replace the wholeblock

























Soft line wrapping support :Uses the hard line wrapping, but storing information aboutwrapped blocks

Un-wraps blocks on saveProblem : implied modifications on save always set the documentstate to dirty







Soft line wrapping support :Uses the hard line wrapping, but storing information aboutwrapped blocksUn-wraps blocks on save

Problem : implied modifications on save always set the documentstate to dirty







Soft line wrapping support :Uses the hard line wrapping, but storing information aboutwrapped blocksUn-wraps blocks on saveProblem : implied modifications on save always set the documentstate to dirty



Questions ?

Any question ?


Technology

ReST Editor - Eclipse Demo Camp Grenoble 2011