Shira-3749/rstpad

Standalone reStructuredText editor with live preview (native app)

RSTPad

reStructuredText editor with live preview.

Contents

• Features
• Known limitations
• Implementation details
• Compilation
  • Prerequisites
  • Build configuration
  • Windows deployment
  • OS X deployment
  • Other platforms

Features

• live preview with autoscroll
• configurable orientation (horizontal / vertical)
• search & replace
• toolbar with common elements:
  • headings
  • bold, italic
  • inline code
  • code blocks
  • horizontal rule
  • lists
  • link
  • image
• inserting highlighted code blocks (Pygments)
  • autocomplete for known lexer names
• built-in help pages
  • syntax cheat sheet
  • directives
• export to PDF

Known limitations

• UTF-8 documents only

Implementation details

• the application contains an embedded Python interpreter
  • Python libraries are located in the application's directory / bundle
• the Docutils library is used to convert RST to HTML on the fly
  • the converstion is done in a separate thread
  • resources/preview/docutils_extensions.py overrides some of the HTML writer's methods to insert additional tags and attributes
• HTML output is displayed using Qt WebEngine
  • external links are delegated to QDesktopServices
  • autoscroll is implemented in JavaScript
  • the preview is "frozen" during loading and autoscrolling to allow for smooth transitions (a previously rendered frame is used for the duration)

Compilation

Prerequisites

• QT 5.8 & Qt Creator
• Python 2.7 (32bit or 64bit depending on the used compiler)
• Pygments (tested with 2.1.3)
• Docutils (tested with 0.13, revision 7975)

Build configuration

Note

• The paths used below (such as C:/python) are just examples. Use actual paths :)
• Use forward slashes in all paths. Omit trailing slashes.
• OS X notes and examples assume that Python 2.7 has been installed using Homebrew. Your paths may vary.

Copy rstpad.local.pro.dist, name it rstpad.local.pro and set the following variables:

• PYTHON_LINK
  • Python linker flags
  • Windows: -LC:/python/libs -lpython27
  • OS X: use the python-config utility to determine linker flags:
    • python2.7-config --ldflags
• PYTHON_INCLUDE_PATH
  • path to a directory containing Python's header files
    • Windows: C:/python/include
    • OS X: /usr/include/python2.7
• PYTHON_SYS_PATH
  • path to a directory containing:
    • libs.zip - the Python standard library as a ZIP archive
    • pygments, docutils - library directories (these cannot be inside libs.zip)
    • any .pyd, .dll and .so modules that should be available in a standard Python installation
  • .pyc files should be excluded

Windows deployment

1. Use the Windows Deployment Tool with the release binary to fetch required DLLs.

   Example: windeployqt.exe --release --no-translations rstpad.exe

2. Locate and copy the correct python27.dll file or the application won't work on machines without Python 2.7 installed.

   • possible locations depend on how you've installed Python and on its version:
     • C:\Windows\System\python27.dll
     • C:\Windows\SysWoW64\python27.dll
   • make sure you're ussing the correct version (32 vs 64bit)

OS X deployment

Use the Mac Deployment Tool to convert the resulting application into a .dmg file:

macdeployqt RSTPad.app -dmg

Other platforms

Not tested yet. You're on your own :)