docutils/docs/user/links.txt

   1 =====================
   2  Docutils_ Link List
   3 =====================
   4
   5 :Author: Lea Wiemann, the Docutils team
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. title:: Docutils Links
  12
  13 .. contents::
  14
  15 This document contains links users of Docutils and reStructuredText
  16 may find useful.  Many of the projects
  17 listed here are hosted in the `Docutils Sandbox`_.  If you have
  18 something to publish, you can get write access, too!
  19
  20 The most current version of this link list can always be found at
  21 http://docutils.sourceforge.net/docs/user/links.html.
  22
  23 .. _Docutils: http://docutils.sourceforge.net/
  24 .. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
  25
  26
  27 Editors
  28 -------
  29
  30 Advanced text editors with reStructuredText support, IDEs, and docutils GUIs:
  31
  32 * Emacs `rst mode <http://docutils.sf.net/tools/editors/emacs>`__.
  33
  34 * `Vim <http://www.vim.org/index.php>`__:
  35
  36   - `reStructuredText syntax highlighting mode
  37     <http://www.vim.org/scripts/script.php?script_id=973>`__,
  38
  39   - `VST <http://www.vim.org/scripts/script.php?script_id=1334>`__ (Vim
  40     reStructuredText) plugin for Vim7 with folding.
  41
  42   - `VOoM <http://www.vim.org/scripts/script.php?script_id=2657>`__
  43     plugin for Vim that emulates two-pane outliner with
  44     support for reStructuredText (since version 4.0b2).
  45
  46   - `Riv: Take notes in rst <https://github.com/Rykka/riv.vim>`__ Vim
  47     plugin to take notes in reStructured text.
  48
  49 * `JED <http://www.jedsoft.org/jed/>`__ programmers editor with
  50   `rst mode <http://jedmodes.sf.net/mode/rst/>`__
  51
  52 * `reStructuredText editor plug-in for Eclipse`__
  53
  54   __ http://resteditor.sf.net/
  55
  56 * Gnome's gedit offers syntax highlighting and a reST preview pane.
  57
  58   Latest version of the plugin is available from `bittner @ github`_
  59   (See also: `Gedit third party plugins`__).
  60
  61   __ https://wiki.gnome.org/Apps/Gedit/ThirdPartyPlugins-v3.8
  62
  63   .. _bittner @ github:  https://github.com/bittner/gedit-reST-plugin
  64
  65 * A BBEdit_/TextWrangler `language module`__ for editing reST documents.
  66
  67   .. _BBEdit: https://en.wikipedia.org/wiki/BBEdit
  68   __ http://ericfromcanada.bitbucket.org/
  69
  70 * Gunnar Schwant's DocFactory_ is a wxPython GUI application for
  71   Docutils.
  72
  73 * ReSTedit_ by Bill Bumgarner is a Docutils GUI for Mac OS X.
  74
  75 * Leo_ is an outliner_, written in Python using PyQt. It can be used as IDE
  76   for literal programming, as a filing cabinet holding any kind of data and
  77   as `document editor`__ with outlines containing reStructuredText markup.
  78
  79   .. _outliner: http://en.wikipedia.org/wiki/Outliner
  80   __ http://leoeditor.com/tutorial-rst3.html
  81
  82 * `NoTex <https://notex.ch>`_ is a browser-based reStructuredText editor
  83   with syntax highlighting and PDF/HTML export functionality using Sphinx.
  84
  85 * `rsted <https://github.com/anru/rsted>`_ is a "simple online editor for
  86   reStructuredText on Flask". You can try it on http://rst.ninjs.org/
  87
  88 .. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
  89 .. _ReSTedit: http://www.friday.com/bbum/index.php?s=restedit
  90 .. _Leo: http://leoeditor.com/
  91
  92
  93 Export
  94 ------
  95
  96 Convert reStructuredText to other formats:
  97
  98 PDF
  99 ```
 100
 101 * `rst2pdf (reportlab)
 102   <http://rst2pdf.googlecode.com>`_ is a tool to go
 103   directly from reStructuredText to PDF, via `reportlab
 104   <http://www.reportlab.org/rl_toolkit.html>`_. No LaTeX installation is
 105   required.
 106
 107 * `rst2pdf (pdflatex)
 108   <http://docutils.sourceforge.net/sandbox/blais/rst2pdf/>`_ by Martin Blais
 109   is a minimal front end producing LaTeX, compiling the LaTeX file, getting
 110   the produced output to the destination location and finally deleting all
 111   the messy temporary files that this process generates.
 112
 113 * `rst2pdf (rubber)
 114   <http://docutils.sf.net/sandbox/rst2pdf/README.html>`_ is
 115   a front end for the generation of PDF documents from a reStructuredText
 116   source via LaTeX in one step cleaning up intermediate files. It uses the
 117   `rubber <http://iml.univ-mrs.fr/~beffara/soft/rubber/>`_ Python wrapper
 118   for LaTeX and friends.
 119
 120 * ``py.rest`` from the Codespeak `py Lib scripts`_ converts
 121   reStructuredText files to HTML and PDF (cleaning up the intermediate
 122   latex files).  Similar to ``buildhtml.py``, it looks recursively for
 123   .txt files in the given PATHS.
 124
 125 * rlpdf_ is another PDF Writer based on ReportLabs.
 126
 127 * RinohType_ is a pure Python PDF Writer based on a document template and a
 128   style sheet (beta).
 129
 130 .. _py Lib scripts: http://codespeak.net/py/dist/bin.html
 131 .. _rlpdf: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
 132 .. _RinohType: http://pypi.python.org/pypi/RinohType/0.2.1
 133
 134 OpenOffice
 135 ``````````
 136
 137 * Since version 0.5, the odtwriter_ by Dave Kuhlman is part of the Docutils_
 138   core.
 139
 140 .. _odtwriter: http://docutils.sf.net/docs/user/odt.html
 141
 142
 143 website generators and HTML variants
 144 ````````````````````````````````````
 145
 146 * The Sphinx_ Python Documentation Generator by Georg Brandl was originally
 147   created to translate the `Python documentation`_, and is now `used by
 148   <http://sphinx.pocoo.org/examples.html>`__ a wide choice of projects.
 149
 150   It can generate complete web sites (interlinked and indexed HTML pages),
 151   ePub, PDF, and others [#]_ from a set of rst source files.
 152
 153   .. [#] see http://sphinx-doc.org/config.html#options-for-epub-output
 154   .. _Sphinx: http://sphinx.pocoo.org/
 155
 156 * The Nikola_ static site generator, uses reStructuredText by
 157   default.
 158
 159   .. _nikola:  http://getnikola.com/
 160
 161 * Pelican_ is a static site generator (mainly for blogs). Articles/pages can
 162   be written in reStructuredText or Markdown format.
 163
 164   .. _pelican: http://docs.getpelican.com
 165
 166 * tinkerer_ is a static bloggin framework based on Sphinx_.
 167
 168   .. _tinkerer: http://tinkerer.me
 169
 170 * rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht
 171   template, for use with ht2html_.
 172
 173   .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
 174   .. _ht2html: http://ht2html.sourceforge.net/
 175
 176 * htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation
 177   bars.
 178
 179   .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
 180
 181 * rest2web_, by Michael Foord, is a tool for creating web sites with
 182   reStructuredText.
 183
 184   .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 185
 186 * rst2chm_ by Oliver Rutherfurd, generates Microsoft HTML Help files from
 187   reStructuredText files.
 188
 189   .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 190
 191 * `html4strict <http://docutils.sf.net/sandbox/html4strict/>`__
 192   produces XHTML that strictly conforms to the XHTML 1.0 specification.
 193
 194 * `html4trans <http://docutils.sf.net/sandbox/html4trans/>`__
 195   produces XHTML conforming to the version 1.0 Transitional DTD that
 196   contains enough formatting information to be viewed by a lightweight HTML
 197   browser without CSS support.
 198
 199 * A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS
 200   (stylesheets).
 201
 202   .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 203
 204 ePub
 205 ````
 206
 207 * The `rst2epub`_ project by Robert Wierschke converts simple
 208   reStructuredText doucments into valid epub files.
 209
 210   .. simple but well structured with classes/modules for epub components,
 211      and a standard ``setup.py`` installation file.
 212
 213 * rst2epub2_ by Matt Harrison includes the epublib (originally by Tim
 214   Tambin) and a rst2epub.py executable for the conversion.
 215
 216 * Sphinx_ provides ePub as output option, too.
 217
 218 .. _rst2epub: https://bitbucket.org/wierob/rst2epub
 219 .. _rst2epub2: https://github.com/mattharrison/rst2epub2
 220
 221
 222 Others
 223 ``````
 224
 225 * Pandoc_ is a document converter that can write Markdown, reStructuredText,
 226   HTML, LaTeX, RTF, DocBook XML, and S5.
 227
 228 * restxsl_ by Michael Alyn Miller, lets you transform reStructuredText
 229   documents into XML/XHTML files using XSLT stylesheets.
 230
 231 * An `XSLT script`__ by Ladislav Lhotka enables reStructuredText annotations
 232   to be included in RELAG NG XML schemas.
 233
 234   __ http://www.cesnet.cz/doc/techzpravy/2006/rngrest/
 235
 236 * `DocBook Writer`_ by Oliver Rutherfurd.
 237
 238 * Nabu_, written by Martin Blais, is a publishing system which
 239   extracts information from reStructuredText documents and stores it
 240   in a database.  Python knowledge is required to write extractor
 241   functions (see `Writing an Extractor`_) and to retrieve the data
 242   from the database again.
 243
 244 * The `pickle writer`_ by Martin Blais pickles the document tree to a binary
 245   string. Later unpickling will allow you to publish with other Writers.
 246
 247 * The `Texinfo Writer`_, by Jon Waltman converts reStructuredText to
 248   Texinfo, the documentation format used by the GNU project and the
 249   Emacs text editor.  Texinfo can be used to produce multiple output
 250   formats, including HTML, PDF, and Info.
 251
 252 * For `confluence CMS`_ see https://github.com/netresearch/rst2confluence.
 253
 254 * Deploying into wikis might be aided by deploy-rst_.
 255
 256 .. _Pandoc: http://sophos.berkeley.edu/macfarlane/pandoc/
 257 .. _restxsl: http://www.strangeGizmo.com/products/restxsl/
 258 .. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
 259 .. _Nabu: http://furius.ca/nabu/
 260 .. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
 261 .. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
 262 .. _Texinfo Writer: http://docutils.sf.net/sandbox/texinfo-writer/README.html
 263 .. _confluence CMS: http://www.atlassian.com/software/confluence
 264 .. _deploy-rst: https://github.com/netresearch/deploy-rst
 265
 266
 267 Import
 268 ------
 269
 270 Convert other formats to reStructuredText:
 271
 272 * sxw2rest_, by Trent W. Buck, converts StarOffice XML Writer (SXW)
 273   files to reStructuredText.
 274
 275 * xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
 276   dumps of the document tree (e.g. created with rst2xml.py) back to
 277   reStructuredText.
 278
 279 * xhtml2rest_, written by Antonios Christofides, is a simple utility
 280   to convert XHTML to reStructuredText.
 281
 282 * DashTable_ by Gustav Klopp converts HTML tables into reStructuredText.
 283   Colspan and Rowspan supported!
 284
 285   .. _DashTable: https://github.com/gustavklopp/DashTable
 286
 287 * Sphinx_ includes a `LaTeX to Rst converter
 288   <http://svn.python.org/projects/doctools/converter/>`__ in its source code
 289   (trimmed to importing the old Python docs).
 290
 291 * Pandoc_ can read Markdown and (subsets of) HTML, and LaTeX and export to
 292   (amongst others) reStructuredText.
 293
 294 * PySource_, by Tony Ibbs, is an experimental Python source Reader.
 295   There is some related code in David Goodger's sandbox
 296   (pysource_reader_) and a `Python Source Reader`_ document.
 297
 298 .. _sxw2rest: http://twb.ath.cx/~twb/darcs/sxw2rest/
 299 .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
 300 .. _xhtml2rest: http://docutils.sf.net/sandbox/wiemann/xhtml2rest/
 301
 302 .. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/
 303 .. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/
 304 .. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
 305
 306
 307 Extensions
 308 ----------
 309
 310 Extend the reStructuredText syntax or the features of Docutils.
 311 More extensions are in the `Docutils Sandbox`_.
 312
 313 * Beni Cherniavsky has written a generic `preprocessing module`_ for
 314   roles and/or directives and built preprocessors for TeX math for
 315   both LaTeX and HTML output on top of it.
 316
 317 * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
 318   to handle everything one might do with Docutils.
 319
 320 * The `ASCII art to SVG converter`_ (aafigure) developed by
 321   Chris Liechti can parse ASCII art images, embedded in reST documents and
 322   output an image. This would mean that simple illustrations could be
 323   embedded as ASCII art in the reST source and still look nice when
 324   converted to e.g. HTML
 325
 326 * zot4rst_ by Erik Hetzner is an extension that allows users to write reST
 327   documents using citations from a Zotero_ library.
 328
 329 * Quick and easy publishing reStructuredText source files as blog posts
 330   on blogger.com is possible with `rst2blogger`_ .
 331
 332 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
 333 .. _Makefile: http://docutils.sf.net/sandbox/cben/make/
 334 .. _ASCII art to SVG converter:
 335    http://docutils.sf.net/sandbox/cliechti/aafigure/
 336 .. _zot4rst: http://e6h.org/~egh/hg/zotero-plain
 337 .. _Zotero: http://www.zotero.org/
 338 .. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
 339
 340
 341 Related Applications
 342 --------------------
 343
 344 Applications using docutils/reStructuredText and helper applications.
 345
 346 * For Wikis, please see the `FAQ entry about Wikis`_.
 347
 348 * For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 349
 350 * `Project Gutenberg`_ uses a customized version of Docutils with it's own
 351   xetex- and nroff-writer and epub generator.
 352
 353 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 354 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
 355 .. _Project Gutenberg: http://www.gutenberg.org
 356
 357 Tools
 358 `````
 359
 360 * rstcheck_ Checks syntax of reStructuredText and code blocks nested within
 361   it. (Using the Sphinx syntax "code-block" for the "code" directive.)
 362
 363   .. _rstcheck: https://pypi.python.org/pypi/rstcheck
 364
 365 * restview_ is a viewer for ReStructuredText documents.
 366
 367   Pass the name of a ReStructuredText document to restview, and it will
 368   launch a web server on localhost:random-port and open a web browser. It
 369   will also watch for changes in that file and automatically reload and
 370   rerender it. This is very convenient for previewing a document while
 371   you're editing it.
 372
 373   .. _restview: http://mg.pov.lt/restview/
 374
 375
 376 Development
 377 ```````````
 378
 379 * Sphinx_ extends the ReStructuredText syntax to better support the
 380   documentation of Software (and other) *projects* (but other documents
 381   can be written with it too).
 382
 383   Since version 2.6, the `Python documentation`_ is based on
 384   reStructuredText and Sphinx.
 385
 386 * Trac_, a project management and bug/issue tracking system, supports
 387   `using reStructuredText
 388   <http://trac.edgewall.org/wiki/WikiRestructuredText>`__ as an
 389   alternative to wiki markup.
 390
 391 * PyLit_ provides a bidirectional text <--> code converter for *literate
 392   programming with reStructuredText*.
 393
 394 * If you are developing a Qt app, rst2qhc_ lets you generate the whole help
 395   automatically from reStructuredText. That includes keywords, TOC,
 396   multiple manuals per project, filters, project file, collection project
 397   file, and more.
 398
 399 .. _Python documentation: http://docs.python.org/
 400 .. _Trac: http://trac.edgewall.org/
 401 .. _PyLit: http://repo.or.cz/pylit.git
 402 .. _rst2qhc: http://rst2qhc.googlecode.com
 403
 404
 405 CMS Systems
 406 ```````````
 407
 408 * Plone_ and Zope_ both support reStructuredText markup.
 409 * ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope_"
 410   application that is complete and ready to install.
 411
 412 .. _Plone: http://plone.org/
 413 .. _Zope: http://www.zope.org/
 414 .. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
 415
 416
 417 Presentations
 418 `````````````
 419
 420 * rst2html5_ transform restructuredtext documents to html5 + twitter's
 421   bootstrap css, deck.js or reveal.js
 422
 423 * landslide_ generates HTML5 slideshows from markdown, ReST, or textile.
 424
 425 * `native support for S5 <slide-shows.s5.html>`_.
 426
 427 * The `PythonPoint interface`_ by Richard Jones produces PDF
 428   presentations using ReportLabs' PythonPoint_.
 429
 430 * rst2beamer_ generates a LaTeX source that uses the `Beamer` document class.
 431   Can be converted to PDF slides with pdfLaTeX/XeLaTeX/LuaLaTeX.
 432
 433 * InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
 434   reStructuredText for markup, although it renders only a subset of rst.
 435
 436 * rst2outline_ translates a reStructuredText document to a plain text
 437   outline. This can then be transformed to PowerPoint.
 438
 439 * Pandoc_ can also be used to produce slides, as shown in this
 440   `Pandoc Slides Demo`_
 441
 442 .. _PythonPoint: http://www.reportlab.org/python_point.html
 443 .. _PythonPoint interface: http://docutils.sf.net/sandbox/richard/pythonpoint/
 444 .. _rst2beamer: http://docutils.sf.net/sandbox/rst2beamer/
 445 .. _Inkscape: http://inkscape.org/
 446 .. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
 447 .. _rst2html5: https://github.com/marianoguerra/rst2html5
 448 .. _landslide: https://github.com/adamzap/landslide
 449 .. _rst2outline: http://docutils.sf.net/sandbox/rst2outline/
 450 .. _Pandoc Slides Demo:
 451    http://johnmacfarlane.net/pandoc/demo/example9/producing-slide-shows-with-pandoc