SF.net SVN: docutils:[10148] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Tue, 27 May 2025 06:17:29 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10148
http://sourceforge.net/p/docutils/code/10148
Author: milde
Date: 2025-05-27 06:17:22 +0000 (Tue, 27 May 2025)
Log Message:
-----------
Documentation Update
Update Link List:
reorganize, fix links, remove broken links and dead projects.
Update "transforms" documentation:
add cross-links, update, small edits.
Various minor documentation fixes.
Modified Paths:
--------------
trunk/docutils/FAQ.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/api/transforms.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/links.rst
Modified: trunk/docutils/FAQ.rst
===================================================================
--- trunk/docutils/FAQ.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/FAQ.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -382,18 +382,10 @@
Are there any Weblog (Blog) projects that use reStructuredText syntax?
----------------------------------------------------------------------
-With no implied endorsement or recommendation, and in no particular
-order:
+See the `Docutils Links`_.
-* `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__
-* `PyBloxsom <http://pyblosxom.github.io/>`__
-* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
-* `Pelican <http://blog.getpelican.com/>`__
- (also listed `on PyPi <http://pypi.python.org/pypi/pelican>`__)
-
Please `let us know`_ of any other reStructuredText Blogs.
-
.. _Can lists be indented without generating block quotes?:
How should I mark up lists?
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -164,8 +164,8 @@
* Remove the input_encoding_ auto-detection code in Docutils 1.0.
* Remove the "TransformSpec.unknown_reference_resolvers" hook chain
- in Docutils 1.0. Use a transform, see
- `transforms.references.CitationReferences` for an example.
+ in Docutils 1.0. Use a transform_,
+ see `transforms.references.CitationReferences` for an example.
* Remove `parsers.rst.roles.set_classes()` and
`parsers.rst.roles.normalized_role_options()`
@@ -209,10 +209,8 @@
__ docs/api/publisher.html#string-i-o
* Move math format conversion from docutils/utils/math (called from
- docutils/writers/_html_base.py) to a transform__.
+ docutils/writers/_html_base.py) to a transform_.
- __ docs/ref/transforms.html
-
* If the environment variable `SOURCE_DATE_EPOCH`_ is set, the `"date"`_
directive and the timestamp inserted by the "datestamp_"
configuration setting will use its value instead of the current time to
@@ -1441,11 +1439,11 @@
==========
.. _HISTORY: HISTORY.html
-.. _Python 3 compatibility: README.html#python-3-compatibility
+.. _transform: docs/api/transforms.html
+
.. _Docutils Document Model:
.. _Docutils XML: docs/ref/doctree.html
-.. _"refname" attribute: docs/ref/doctree.html#refname
.. _"colwidth" attribute: docs/ref/doctree.html#colwidth
.. _<doctest_block>: docs/ref/doctree.html#doctest-block
@@ -1494,7 +1492,6 @@
.. _docutils-cli.py:
.. _generic command line front end tool:
docs/user/tools.html#generic-command-line-front-end
-.. _rst2html.py:
.. _rst2html: docs/user/tools.html#rst2html
.. _rst2html4: docs/user/tools.html#rst2html4
.. _rst2html5: docs/user/tools.html#rst2html5
Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/docs/api/transforms.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -22,29 +22,30 @@
`interpreted text`_, and do other context-sensitive processing.
Each transform is a subclass of `docutils.transforms.Transform`.
-There are `transforms added by components`_, others (e.g.
-``parts.Contents``) are added by the parser, if a corresponding directive_ is
-found in the document.
+Most transforms are added by components, others (e.g. `parts.Contents`) are
+added by the parser if a corresponding directive_ is found in the document.
To add a transform, components (objects inheriting from
`docutils.Component` like Readers, Parsers, Writers, Input, Output) overwrite
-the ``get_transforms()`` method of their base class. After the Reader has
+the `get_transforms()` method of their base class. After the Reader has
finished processing, the Publisher calls
-``Transformer.populate_from_components()`` with a list of components and all
-transforms returned by the component's ``get_transforms()`` method are
-stored in a `transformer object` attached to the document tree.
+`Transformer.populate_from_components()` with a list of components and all
+transforms returned by the component's `get_transforms()` method are
+stored in a `Transformer` object attached to the document tree.
-For more about transforms and the Transformer object, see also `PEP
-258`_. (The ``default_transforms()`` attribute of component classes mentioned
-there is deprecated. Use the ``get_transforms()`` method instead.)
+For more info about transforms and the `Transformer` object,
+see also `PEP 258`_. [#]_
+.. [#] The `default_transforms()` attribute of component classes mentioned
+ in PEP 258 is deprecated. Use the `get_transforms()` method instead.
+
.. _priority:
Transforms Listed in Priority Order
===================================
-Transform classes each have a `default priority` attribute which is used by
+Transform classes each have a `default_priority` attribute which is used by
the Transformer to apply transforms in order (low to high). The default
priority can be overridden when adding transforms to the Transformer object.
@@ -52,79 +53,79 @@
================================== ============================ ========
Transform: module.Class Added By Priority
================================== ============================ ========
-misc_.ClassAttribute `"class"`_ (d/p) 210
+misc_.ClassAttribute `"class"`_ (d/p) _`210`
-references_.Substitutions standalone (r), pep (r) 220
+references_.Substitutions standalone_ (r), pep_ (r) _`220`
-references_.PropagateTargets standalone (r), pep (r) 260
+references_.PropagateTargets standalone_ (r), pep_ (r) _`260`
-frontmatter.\ DocTitle_ standalone (r) 320
+frontmatter.\ DocTitle_ standalone_ (r) _`320`
-frontmatter.\ DocInfo_ standalone (r) 340
+frontmatter.\ DocInfo_ standalone_ (r) _`340`
-frontmatter.\ SectSubTitle_ standalone (r) 350
+frontmatter.\ SectSubTitle_ standalone_ (r) _`350`
-peps_.Headers pep (r) 360
+peps_.Headers pep_ (r) _`360`
-peps_.Contents pep (r) 380
+peps_.Contents pep_ (r) _`380`
-universal_.StripClassesAndElements Writer (w) 420
+universal_.StripClassesAndElements writers_ (w) _`420`
-references_.AnonymousHyperlinks standalone (r), pep (r) 440
+references_.AnonymousHyperlinks standalone_ (r), pep_ (r) _`440`
-references_.IndirectHyperlinks standalone (r), pep (r) 460
+references_.IndirectHyperlinks standalone_ (r), pep_ (r) _`460`
-peps_.TargetNotes pep (r) 520
+peps_.TargetNotes pep_ (r) _`520`
-references_.TargetNotes peps.TargetNotes (t/p) 0
+references_.TargetNotes peps.TargetNotes (t/p) 0
-misc_.CallBack peps.TargetNotes (t/p) 1
+misc_.CallBack peps.TargetNotes (t/p) 1
-references_.TargetNotes `"target-notes"`_ (d/p) 540
+references_.TargetNotes `"target-notes"`_ (d/p) _`540`
-references_.Footnotes standalone (r), pep (r) 620
+references_.Footnotes standalone_ (r), pep_ (r) _`620`
-references_.ExternalTargets standalone (r), pep (r) 640
+references_.ExternalTargets standalone_ (r), pep_ (r) _`640`
-references_.InternalTargets standalone (r), pep (r) 660
+references_.InternalTargets standalone_ (r), pep_ (r) _`660`
-parts_.SectNum `"sectnum"`_ (d/p) 710
+parts_.SectNum `"sectnum"`_ (d/p) _`710`
-parts_.Contents `"contents"`_ (d/p), 720
+parts_.Contents `"contents"`_ (d/p), _`720`
peps.Contents (t/p)
-universal_.StripComments Reader (r) 740
+universal_.StripComments readers_ (r) _`740`
-peps_.PEPZero peps.Headers (t/p) 760
+peps_.PEPZero peps.Headers (t/p) _`760`
-references_.CitationReferences latex2e (w) 770
+references_.CitationReferences latex2e_ (w) _`770`
-components.Filter *not used* 780
+components.Filter *not used* _`780`
-universal_.Decorations Reader (r) 820
+universal_.Decorations readers_ (r) _`820`
-misc_.Transitions standalone (r), pep (r) 830
+misc_.Transitions standalone_ (r), pep_ (r) _`830`
-universal_.Validate Parser 835
+universal_.Validate parsers_ (p) _`835`
-universal_.ExposeInternals Reader (r) 840
+universal_.ExposeInternals readers_ (r) _`840`
-references_.DanglingReferences standalone (r), pep (r) 850
+references_.DanglingReferences standalone_ (r), pep_ (r) _`850`
-universal_.SmartQuotes Parser 855
+universal_.SmartQuotes rst_ (p) _`855`
-universal_.Messages Writer (w) 860
+universal_.Messages writers_ (w) _`860`
-universal_.FilterMessages Writer (w) 870
+universal_.FilterMessages writers_ (w) _`870`
-universal_.TestMessages DocutilsTestSupport 880
+universal_.TestMessages DocutilsTestSupport _`880`
-writer_aux_.Compound *not used, to be removed* 910
+writer_aux_.Compound *not used, to be removed* _`910`
-writer_aux_.Admonitions _html_base (w), 920
- latex2e (w)
+writer_aux_.Admonitions `_html_base`_ (w), _`920`
+ latex2e_ (w)
-misc_.CallBack n/a 990
+misc_.CallBack n/a _`990`
================================== ============================ ========
Key:
@@ -155,62 +156,81 @@
==== ==== ================================================
-Transforms added by components
-===============================
+Transforms Added by Components
+==============================
+.. _readers:
+
readers.Reader:
- | universal.Decorations,
- | universal.ExposeInternals,
- | universal.StripComments
+ | universal.StripComments (740_)
+ | universal.Decorations (820_)
+ | universal.ExposeInternals (840_)
readers.ReReader:
None
+ .. _standalone:
+
readers.standalone.Reader:
- | references.Substitutions,
- | references.PropagateTargets,
- | frontmatter.DocTitle,
- | frontmatter.SectionSubTitle,
- | frontmatter.DocInfo,
- | references.AnonymousHyperlinks,
- | references.IndirectHyperlinks,
- | references.Footnotes,
- | references.ExternalTargets,
- | references.InternalTargets,
- | references.DanglingReferences,
- | misc.Transitions
+ | references.Substitutions (220_)
+ | references.PropagateTargets (260_)
+ | frontmatter.\ DocTitle_ (320_)
+ | frontmatter.\ DocInfo_ (340_)
+ | frontmatter.\ SectSubTitle_ (350_)
+ | references.AnonymousHyperlinks (440_)
+ | references.IndirectHyperlinks (460_)
+ | references.Footnotes (620_)
+ | references.ExternalTargets (640_)
+ | references.InternalTargets (660_)
+ | misc.Transitions (830_)
+ | references.DanglingReferences (850_)
+ .. _pep:
+
readers.pep.Reader:
- | references.Substitutions,
- | references.PropagateTargets,
- | references.AnonymousHyperlinks,
- | references.IndirectHyperlinks,
- | references.Footnotes,
- | references.ExternalTargets,
- | references.InternalTargets,
- | references.DanglingReferences,
- | misc.Transitions,
- | peps.Headers,
- | peps.Contents,
- | peps.TargetNotes
+ | references.Substitutions (220_)
+ | references.PropagateTargets (260_)
+ | peps.Headers (360_)
+ | peps.Contents (380_)
+ | references.AnonymousHyperlinks (440_)
+ | references.IndirectHyperlinks (460_)
+ | peps.TargetNotes (520_)
+ | references.Footnotes (620_)
+ | references.ExternalTargets (640_)
+ | references.InternalTargets (660_)
+ | misc.Transitions (830_)
+ | references.DanglingReferences (850_)
+ .. _parsers:
+
+parsers.Parser
+ universal_.Validate (835_)
+
+ .. _rst:
+
parsers.rst.Parser
- universal.SmartQuotes
+ universal.SmartQuotes (855_)
+ .. _writers:
+
writers.Writer:
- | universal.Messages,
- | universal.FilterMessages,
- | universal.StripClassesAndElements
+ | universal.StripClassesAndElements (420_)
+ | universal.Messages (860_)
+ | universal.FilterMessages (870_)
writers.UnfilteredWriter
None
+ .. _latex2e:
+
writers.latex2e.Writer
- writer_aux.Admonitions
- references.CitationReferences
+ | writer_aux.Admonitions (920_)
+ | references.CitationReferences (770_)
+ .. _`_html_base`:
+
writers._html_base.Writer:
- writer_aux.Admonitions
+ writer_aux.Admonitions (920_)
writers.odf_odt.Writer:
removes references.DanglingReferences
@@ -233,8 +253,8 @@
.. class:: field-indent-12em
:Module: frontmatter_
-:Added by: standalone Reader
-:Default priority_: 340
+:Added by: standalone_ Reader
+:Default priority_: 340_
:Configuration_ setting: docinfo_xform_ (default: True)
Given a document starting [#pre-docinfo]_ with a field list, the DocInfo
@@ -288,8 +308,8 @@
.. class:: field-indent-12em
:Module: frontmatter_
-:Added by: standalone Reader
-:Default priority_: 320
+:Added by: standalone_ Reader
+:Default priority_: 320_
:Configuration_ setting: doctitle_xform_ (default: True)
Under the conditions explained below, the DocTitle transform converts
@@ -433,8 +453,8 @@
.. class:: field-indent-12em
:Module: frontmatter_
-:Added by: standalone Reader
-:Default priority_: 350
+:Added by: standalone_ Reader
+:Default priority_: 350_
:Configuration_ setting: sectsubtitle_xform_ (default: False)
The SectSubTitle transform works like `step 2`_ of the DocTitle_
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/docs/ref/doctree.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -4805,8 +4805,9 @@
On a `\<target>`_ element, ``refname`` indicates an `indirect target`_
which may resolve to either an internal or external reference.
-Docutils transforms_ replace the ``refname`` attribute with a refid_
-pointing to the same element.
+Docutils transforms_ replace the ``refname`` attribute with
+a refid_ (refering to the same element) or a refuri_ (refering to an
+external ressource).
``refuri``
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/docs/user/config.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -1978,7 +1978,7 @@
use_bibtex
~~~~~~~~~~
-List of style and database(s) for the experimental `BibTeX` support
+List of style and database(s) for the experimental `BibTeX`_ support
(comma-separated_). Example::
--use-bibtex=unsrt,mydb1,mydb2
@@ -1990,6 +1990,8 @@
*Default*: empty list (don't use BibTeX). *Option* ``--use-bibtex``.
+.. _BibTeX: https://www.ctan.org/pkg/bibtex
+
use_latex_abstract
~~~~~~~~~~~~~~~~~~
Use LaTeX abstract environment for the document's abstract_.
Modified: trunk/docutils/docs/user/links.rst
===================================================================
--- trunk/docutils/docs/user/links.rst 2025-05-27 06:15:14 UTC (rev 10147)
+++ trunk/docutils/docs/user/links.rst 2025-05-27 06:17:22 UTC (rev 10148)
@@ -7,481 +7,416 @@
:Author: Lea Wiemann, the Docutils team
:Contact: [email protected]
:Revision: $Revision$
-:Date: $Date$
+:Date: $Date$ [#]_
:Copyright: This document has been placed in the public domain.
+:Abstract: Links that users of Docutils_ and reStructuredText_ may find useful.
.. title:: Docutils Links
.. contents::
+ :depth: 2
-This document contains links that users of Docutils_ and reStructuredText_
-may find useful.
+.. [#] The most current version of this link list can always be found at
+ https://docutils.sourceforge.io/docs/user/links.html. If you find
+ outdated or broken links or want to suggest additions, please `let us
+ know`__ and we'll update the list here.
-The most current version of this link list can always be found at
-https://docutils.sourceforge.io/docs/user/links.html.
-If you find outdated or broken links or want to suggest additions,
-please `let us know`__ and we'll update the list here.
-
.. _Docutils: https://docutils.sourceforge.io/
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
__ mailing-lists.html#docutils-users
-Editors
--------
+Extensions
+==========
-Advanced text editors with reStructuredText support, IDEs, and docutils GUIs:
+Drop-in components and front-end tools for Docutils that extend the
+reStructuredText syntax or feature set.
-* Emacs `rst mode <https://docutils.sourceforge.io/tools/editors/emacs>`__.
+Import
+------
-* `Vim <https://www.vim.org/index.php>`__:
+Markdown
+````````
- - `reStructuredText syntax highlighting mode
- <https://www.vim.org/scripts/script.php?script_id=973>`__,
+* `myst-docutils`_ --- the MyST_ Markdown parser for `single page builds`_.
- - `VST <https://www.vim.org/scripts/script.php?script_id=1334>`__ (Vim
- reStructuredText) plugin for Vim7 with folding.
+ .. _myst-docutils: https://pypi.org/project/myst-docutils/
+ .. _MyST: https://mystmd.org/guide/quickstart-myst-markdown
+ .. _single page builds:
+ https://myst-parser.readthedocs.io/en/latest/docutils.html
- - `VOoM <https://www.vim.org/scripts/script.php?script_id=2657>`__
- plugin for Vim that emulates two-pane outliner with
- support for reStructuredText (since version 4.0b2).
+* pycmark_ --- small, customizable drop-in parser for CommonMark_ Markdown.
- - `Riv: Take notes in rST <https://github.com/Rykka/riv.vim>`__ Vim
- plugin to take notes in reStructured text.
+ .. _pycmark: https://pypi.org/project/pycmark/
+ .. _CommonMark: https://spec.commonmark.org/current/
-* `reStructuredText Language Support for Visual Studio Code`__
- __ https://github.com/vscode-restructuredtext/vscode-restructuredtext
+.. Python 2 only
-* `reStructuredText editor plug-in for Eclipse`__
+ PySource_, by Tony Ibbs, is an experimental Python source Reader.
+ There is some related code in David Goodger's sandbox
+ (pysource_reader_) and a `Python Source Reader`_ document.
- __ http://resteditor.sourceforge.net/
+ .. _PySource: https://docutils.sourceforge.io/sandbox/tibs/pysource/
+ .. _pysource_reader: https://docutils.sourceforge.io/sandbox/davidg/pysource_reader/
+ .. _Python Source Reader: https://docutils.sourceforge.io/docs/dev/pysource.html
-* `JED <https://www.jedsoft.org/jed/>`__ programmers editor with
- `rst mode <httpss://jedmodes.sourceforge.io/mode/rst/>`__
-* Gnome's gedit offers syntax highlighting and a reST preview pane.
- Latest version of the plugin is available from `bittner @ github`_
- (See also: `Gedit third party plugins`__).
+.. Python 2 only
- .. _bittner @ github: https://github.com/bittner/gedit-reST-plugin
- __ https://wiki.gnome.org/Apps/Gedit/ThirdPartyPlugins-v3.8
+ The `ASCII art to SVG converter`_ (aafigure_) developed by
+ Chris Liechti can parse ASCII art images, embedded in reST documents and
+ output an image. This would mean that simple illustrations could be
+ embedded as ASCII art in the reST source and still look nice when
+ converted to e.g. HTML
+ .. _ASCII art to SVG converter:
+ https://docutils.sourceforge.io/sandbox/aafigure/
+ .. _aafigure: https://pypi.org/project/docutils-aafigure/
-* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
- Docutils.
+.. only Python 2
- .. _DocFactory: https://docutils.sourceforge.io/sandbox/gschwant/docfactory/doc/
+ restxsl_ by Michael Alyn Miller, lets you transform reStructuredText
+ documents into XML/XHTML files using XSLT stylesheets.
-* ReSTedit_ by Bill Bumgarner is a Docutils GUI for Mac OS X.
+ .. _restxsl: http://www.strangeGizmo.com/products/restxsl/
- .. _ReSTedit: https://svn.red-bean.com/restedit/trunk/README.html
-* `ReText <https://pypi.org/project/ReText/>`_ is a simple but powerful
- editor for Markdown and reStructuredText markup languages.
- It is written in Python using PyQt libraries.
+Export
+------
-* Leo_ is an outliner_, written in Python using PyQt. It can be used as IDE
- for literal programming, as a filing cabinet holding any kind of data and
- as `document editor`__ with outlines containing reStructuredText markup.
+PDF
+```
- .. _Leo: https://leoeditor.com/
- .. _outliner: https://en.wikipedia.org/wiki/Outliner
- __ https://leoeditor.com/tutorial-rst3.html
+* RinohType_ --- pure Python PDF writer
-* `NoTex <https://notex.ch>`_ is a browser-based reStructuredText editor
- with syntax highlighting and PDF/HTML export functionality using Sphinx.
+ .. _RinohType: https://pypi.python.org/pypi/RinohType
-* `rsted <https://github.com/anru/rsted>`_ is a "simple online editor for
- reStructuredText on Flask". You can try it on http://rst.ninjs.org/
+* `rst2pdf (reportlab)`__ --- PDF writer based on ReportLab_.
+ __ https://pypi.org/project/rst2pdf/
+ .. _ReportLab: https://pypi.org/project/reportlab/
-Export
-------
+.. only Python 2
-Projects providing additional export routes.
+ `rst2pdf (rubber)`__ --- front end for PDF generation via LaTeX
+ using the rubber_ building system.
-PDF
-```
+ __ https://docutils.sourceforge.io/sandbox/rst2pdf_rubber/README.html
+ .. _rubber: https://gitlab.com/latex-rubber/rubber/
-* `rst2pdf (reportlab)`__ is a tool to go directly from
- reStructuredText to PDF, via ReportLab__. No LaTeX installation
- is required.
+ `rst2pdf (pdflatex)`__ --- minimal front end for PDF generation via LaTeX.
- __ https://pypi.org/project/rst2pdf/
- __ https://pypi.org/project/reportlab/
-
-* `rst2pdf (pdflatex)`__ by Martin Blais is a minimal front end
- producing LaTeX, compiling the LaTeX file, getting the produced
- output to the destination location and finally deleting all the
- messy temporary files that this process generates.
-
__ https://docutils.sourceforge.io/sandbox/blais/rst2pdf/
-* `rst2pdf (rubber)`__ is a front end for the generation of PDF
- documents from a reStructuredText source via LaTeX in one step
- cleaning up intermediate files. It uses the rubber__ Python wrapper
- for LaTeX and friends.
+.. Python 2 only (or broken)
- __ https://docutils.sourceforge.io/sandbox/rst2pdf/README.html
- __ https://launchpad.net/rubber
+ rlpdf_ --- another PDF writer based on ReportLab_.
-* rlpdf_ is another PDF Writer based on ReportLabs.
-
.. _rlpdf: https://docutils.sourceforge.io/sandbox/dreamcatcher/rlpdf/
-* RinohType_ is a pure Python PDF Writer based on a document template and a
- style sheet (beta).
+ >>> from rlpdf import Writer
+ ImportError: cannot import name 'Writer' from partially initialized
+ module 'rlpdf' (most likely due to a circular import)
- .. _RinohType: https://pypi.python.org/pypi/RinohType
-website generators and HTML variants
-````````````````````````````````````
+Others
+``````
-* The Sphinx_ Python Documentation Generator by Georg Brandl was
- originally created to translate the `Python documentation`_.
- In the meantime, there is a wide range of `Projects using Sphinx`__
+* `DocBook Writer`_ (only Python 2)
- It can generate complete web sites (interlinked and indexed HTML pages),
- ePub, LaTeX, and others from a set of rST source files.
+ .. _DocBook Writer: https://docutils.sourceforge.io/sandbox/oliverr/docbook/
- .. _Sphinx: https://www.sphinx-doc.org
- __ https://www.sphinx-doc.org/en/master/examples.html
+* `pickle writer`_ --- "pickle__" the document tree to a binary string.
-* The Nikola_ static site generator, uses reStructuredText by
- default.
+ .. _pickle writer:
+ https://docutils.sourceforge.io/sandbox/blais/pickle_writer/
+ __ https://docs.python.org/3/library/pickle.html
- .. _nikola: https://getnikola.com/
+* rst2confluence__ converts reStructuredText to Confluence__ CMS markup.
-* Pelican_ is a static site generator (mainly for blogs). Articles/pages can
- be written in reStructuredText or Markdown_ format.
+ __ https://github.com/netresearch/rst2confluence
+ __ https://www.atlassian.com/software/confluence
- .. _pelican: https://docs.getpelican.com
+* rst2epub2_ (only Python 2)
-* tinkerer_ is a static bloggin framework based on Sphinx_.
+ .. _rst2epub2: https://github.com/mattharrison/rst2epub2
- .. _tinkerer: https://pypi.org/project/Tinkerer/
+----------------------------------------------------------
-* htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation
- bars.
+There are more extensions in the `Docutils Sandbox`_.
- .. _htmlnav: https://docutils.sourceforge.io/sandbox/gschwant/htmlnav/
+.. _Docutils Sandbox: https://docutils.sourceforge.io/sandbox/README.html
-* rest2web, by Michael Foord, is a tool for creating web sites with
- reStructuredText. Development stalled, there is a fork at
- https://gitlab.com/wavexx/rest2web
-* `html4trans <https://docutils.sourceforge.io/sandbox/html4trans/>`__
- produces XHTML conforming to the version 1.0 Transitional DTD that
- contains enough formatting information to be viewed by a lightweight HTML
- browser without CSS support.
+Tools
+=====
-* A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS
- stylesheets.
+* a Makefile_ for driving Docutils,
- .. _simple HTML writer: https://docutils.sourceforge.io/sandbox/bbum/DocArticle/
+ .. _Makefile: https://docutils.sourceforge.io/sandbox/cben/make/
-ePub
-````
+* rstcheck_ checks syntax of reStructuredText and code blocks nested
+ within it.
-* rst2epub2_ by Matt Harrison includes the epublib (originally by Tim
- Tambin) and a rst2epub.py executable for the conversion.
+ .. _rstcheck: https://pypi.python.org/pypi/rstcheck
- .. _rst2epub2: https://github.com/mattharrison/rst2epub2
+* restview_ --- live preview for reStructuredText documents,
-* Sphinx_ provides ePub as output option, too.
+ .. _restview: https://mg.pov.lt/restview/
-Others
-``````
+Editors
+-------
-* Pandoc_ is a document converter that can write Markdown_,
- reStructuredText, HTML, LaTeX, RTF, DocBook XML, and S5.
+Editors and IDEs with reStructuredText support.
- .. _Pandoc: https://pandoc.org/
+* Eclipse_ IDE with `ReST Editor`__ plug-in.
-* restxsl_ by Michael Alyn Miller, lets you transform reStructuredText
- documents into XML/XHTML files using XSLT stylesheets.
+ .. _Eclipse: https://eclipseide.org/
+ __ http://resteditor.sourceforge.net/
- .. _restxsl: http://www.strangeGizmo.com/products/restxsl/
+* Emacs__ extensible text editor with `rst mode`__.
-* An `XSLT script`__ by Ladislav Lhotka enables reStructuredText annotations
- to be included in RELAG NG XML schemas.
+ __ https://www.gnu.org/software/emacs/
+ __ https://docutils.sourceforge.io/tools/editors/emacs/
- __ https://www.cesnet.cz/doc/techzpravy/2006/rngrest/
+* Geany_ lightweight IDE.
-* `DocBook Writer`_ by Oliver Rutherfurd.
+ .. _geany: http://www.geany.org/
- .. _DocBook Writer: https://docutils.sourceforge.io/sandbox/oliverr/docbook/
+* gedit_ with the gedit-reST-plugin__.
-* Nabu_, written by Martin Blais, is a publishing system which
- extracts information from reStructuredText documents and stores it
- in a database. Python knowledge is required to write extractor
- functions and to retrieve the data from the database again.
+ .. _gedit: https://gedit-text-editor.org/
+ __ https://github.com/bittner/gedit-reST-plugin
- .. _Nabu: https://github.com/blais/nabu
+* JED__ programmers editor with `rst mode`__.
-* The `pickle writer`_ by Martin Blais pickles the document tree to a binary
- string. Later unpickling will allow you to publish with other Writers.
+ __ https://www.jedsoft.org/jed/
+ __ https://jedmodes.sourceforge.io/mode/rst/
- .. _pickle writer: https://docutils.sourceforge.io/sandbox/blais/pickle_writer/
+* Leo_ PIM, IDE and outliner (see `creating documents from outlines`__).
-* The `Texinfo Writer`_, by Jon Waltman converts reStructuredText to
- Texinfo, the documentation format used by the GNU project and the
- Emacs text editor. Texinfo can be used to produce multiple output
- formats, including HTML, PDF, and Info.
+ .. _Leo: https://leo-editor.github.io/leo-editor/
+ __ https://leo-editor.github.io/leo-editor/tutorial-rst3.html
- .. _Texinfo Writer: https://docutils.sourceforge.io/sandbox/texinfo-writer/README.html
+* `Notepad++`_ with reStructuredText_NPP__ (basic syntax highlighting).
-* For `confluence CMS`_ see https://github.com/netresearch/rst2confluence.
+ .. _Notepad++: https://www.notepad-plus-plus.org/
+ __ https://github.com/steenhulthin/reStructuredText_NPP
- .. _confluence CMS: https://www.atlassian.com/software/confluence
+* ReSTedit_ --- Docutils GUI for Mac OS X.
-* Deploying into wikis might be aided by deploy-rst_.
+ .. _ReSTedit: https://svn.red-bean.com/restedit/trunk/README.html
- .. _deploy-rst: https://github.com/netresearch/deploy-rst
+* ReText_ --- editor for markup languages with live preview.
+ .. _ReText: https://pypi.org/project/ReText/
-Import
-------
+* RSTPad_ --- reStructuredText editor with live preview.
-Convert other formats to reStructuredText:
+ .. _RSTPad: https://github.com/shira-374/rstpad?tab=readme-ov-file#rstpad
-* recommonmark_ is a Markdown_ (CommonMark_) parser for
- docutils originally created by Luca Barbato.
+* `Vim <https://www.vim.org/>`__ with
- Docutils "markdown" parser (new in Docutils 0.17) is a wrapper
- around recommonmark.
+ - `rest.vim <https://www.vim.org/scripts/script.php?script_id=973>`__
+ reStructuredText syntax mode,
+ - `VST <https://www.vim.org/scripts/script.php?script_id=1334>`__
+ (Vim reStructuredText) plugin,
+ - `VOoM <https://www.vim.org/scripts/script.php?script_id=2657>`__
+ two-pane text outliner, or
+ - `Riv: <https://github.com/Rykka/riv.vim>`__
+ Notes and wiki in rST.
- .. _recommonmark: https://github.com/rtfd/recommonmark
- .. _Markdown: https://daringfireball.net/projects/markdown/syntax
- .. _CommonMark: https://commonmark.org/
+* `Visual Studio Code`__ with `vscode-restructuredtext`__
+ Language Support extension.
+ __ https://code.visualstudio.com
+ __ https://github.com/vscode-restructuredtext/vscode-restructuredtext
-* sxw2rest_, by Trent W. Buck, converts StarOffice XML Writer (SXW)
- files to reStructuredText. (link down)
- .. _sxw2rest: https://twb.ath.cx/~twb/darcs/sxw2rest/
+.. \http://rst.ninjs.org/ is down, the repository marked as UNMAINTAINED:
-* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
- dumps of the document tree (e.g. created with ``rst2xml``) back to
+ `rsted <https://github.com/anru/rsted>`_: a simple online editor for
reStructuredText.
- .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
+.. last update 2004, Python 2 -> incompatible with Docutils > 0.18
-* xhtml2rest_, written by Antonios Christofides, is a simple utility
- to convert XHTML to reStructuredText.
+ DocFactory_ is a wxPython GUI application for Docutils.
+ The last version (from 2004) still requires Python 2.
- .. _xhtml2rest: https://docutils.sourceforge.io/sandbox/wiemann/xhtml2rest/
+ .. _DocFactory:
+ https://docutils.sourceforge.io/sandbox/gschwant/docfactory/doc/
-* DashTable_ by Gustav Klopp converts HTML tables into reStructuredText.
- Colspan and Rowspan supported!
- .. _DashTable: https://github.com/gustavklopp/DashTable
+Related Applications
+====================
-* Sphinx_ includes a `LaTeX to rST converter
- <https://svn.python.org/projects/doctools/converter/>`__ in its source code
- (trimmed to importing the old Python docs).
+Applications using Docutils/reStructuredText and helper applications.
-* Pandoc_ can read Markdown_ and (subsets of) HTML, and LaTeX and
- export to (amongst others) reStructuredText.
-* PySource_, by Tony Ibbs, is an experimental Python source Reader.
- There is some related code in David Goodger's sandbox
- (pysource_reader_) and a `Python Source Reader`_ document.
-
- .. _PySource: https://docutils.sourceforge.io/sandbox/tibs/pysource/
- .. _pysource_reader: https://docutils.sourceforge.io/sandbox/davidg/pysource_reader/
- .. _Python Source Reader: https://docutils.sourceforge.io/docs/dev/pysource.html
-
-
-Extensions
+Converters
----------
-Extend the reStructuredText syntax or the features of Docutils.
-More extensions are in the `Docutils Sandbox`_.
+Alternative implementations to convert between reStructuredText
+and other formats.
-* Beni Cherniavsky has written a generic `preprocessing module`_ for
- roles and/or directives and built preprocessors for TeX math for
- both LaTeX and HTML output on top of it.
+* Pandoc_ --- universal document converter written in Haskell.
+ Can read/write reStructuredText, DocBook, EPUB, HTML, LaTeX,
+ docx, Markdown, ODT, and more.
- .. _preprocessing module: https://docutils.sourceforge.io/sandbox/cben/rolehack/
+ .. _Pandoc: https://pandoc.org/
-* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
- to handle everything one might do with Docutils.
+* Laika_ --- Site and E-book Generator and Customizable Text Markup
+ Transformer for sbt, Scala and Scala.js.
- .. _Makefile: https://docutils.sourceforge.io/sandbox/cben/make/
+ .. _Laika: https://typelevel.org/Laika/
-* The `ASCII art to SVG converter`_ (aafigure) developed by
- Chris Liechti can parse ASCII art images, embedded in reST documents and
- output an image. This would mean that simple illustrations could be
- embedded as ASCII art in the reST source and still look nice when
- converted to e.g. HTML
+* Nim_ --- system programming language. Supports `Nim-flavoured
+ reStructuredText`__ with the rst__, rstast__, and rstgen__ modules.
+ The Nim compiler provides the ``nim rst2html`` and ``nim rst2latex``
+ sub-commands.
- .. _ASCII art to SVG converter:
- https://docutils.sourceforge.io/sandbox/cliechti/aafigure/
+ .. _Nim: https://nim-lang.org/
+ __ https://nim-lang.org/docs/markdown_rst.html
+ __ https://nim-lang.org/docs/rst.html
+ __ http://nim-lang.org/docs/rstast.html
+ __ http://nim-lang.org/docs/rstgen.html
-* Quick and easy publishing reStructuredText source files as blog posts
- on blogger.com is possible with `rst2blogger`_ .
+* RST__ --- PHP library to parse reStructuredText documents.
- .. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
+ __ https://github.com/Gregwar/RST
-.. _Docutils Sandbox: https://docutils.sourceforge.io/sandbox/README.html
+* Text-Restructured_ --- a set of Perl_ modules to parse reStructuredText
+ documents and output them in various formats.
+ .. _Text-Restructured: https://metacpan.org/dist/Text-Restructured
+ .. _Perl: https://www.perl.org
-Related Applications
---------------------
+* xml2rst_ --- an XSLT stylesheet that converts `Docutils XML`_
+ back to reStructuredText.
-Applications using docutils/reStructuredText and helper applications.
+ .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
+ .. _Docutils XML: ../ref/doctree.html
-* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
+Website Generators
+------------------
-* `Project Gutenberg`_ uses Docutils for its "ebookmaker_"
- xetex, nroff, and epub generator (with some `extensions to rST`__).
+* Sphinx_ Documentation Generator.
- __ http://pgrst.pglaf.org/publish/181/181-h.html
+ .. _Sphinx: https://www.sphinx-doc.org
+* ipsumgenera_ --- static blog generator written in Nim.
-* Text-Restructured_ at CPAN is a set of modules to parse
- reStructuredText documents and output them in various formats written
- in Perl_.
- Up to January 2021, the sources were stored in the Docutils repository_.
- After long inactivity (the last commit was r6498__
- 2010-12-08), ``trunk/prest/`` was moved to the attic.
+ .. _ipsumgenera: https://github.com/dom96/ipsumgenera
- __ https://sourceforge.net/p/docutils/code/6498/
+* Nikola_ --- static site generator.
-.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html
- #are-there-any-wikis-that-use-restructuredtext-syntax
-.. _FAQ entry about Blogs: https://docutils.sourceforge.io/FAQ.html
- #are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
-.. _Project Gutenberg: http://www.gutenberg.org
-.. _ebookmaker: https://pypi.org/project/ebookmaker/
-.. _Perl: https://www.perl.org
-.. _Text-Restructured: https://metacpan.org/dist/Text-Restructured
-.. _repository: ../dev/repository.html
+ .. _nikola: https://getnikola.com/
+* Pelican_ --- another static site generator.
-Wikis
-`````
+ .. _pelican: https://docs.getpelican.com
-* Trac_ supports `using reStructuredText`__ as an alternative to wiki markup.
- This includes support for TracLinks_ from within reStructuredText
- via a custom rST reference-directive or, even easier, an interpreted
- text role "trac".
+* rest2web_ --- simple tool for creating web sites with reStructuredText.
- __ http://trac.edgewall.com//wiki/WikiRestructuredText
+ .. _rest2web: https://gitlab.com/wavexx/rest2web
-* MoinMoin_ includes a `ReStructuredText Parser
- <http://moinmo.in/HelpOnParsers/ReStructuredText>`__.
+* Yozuch_ --- reStructuredText based static blog generator written in Python.
-* Ian Bicking's experimental `wiki module`__ in the sandbox.
+ .. _Yozuch: https://github.com/akrylysov/yozuch
- __ https://docutils.sourceforge.io/sandbox/ianb/wiki
-* Zope-based Zwiki_
- (requires Zope2, which reached end of life on December 31, 2020).
+Wikis
+-----
-.. _TracLinks: http://trac.edgewall.com//wiki/TracLinks
-.. _MoinMoin: http://moinmo.in/
-.. _ZWiki: https://github.com/simonmichael/ZWiki
+* MoinMoin_ includes a `ReStructuredText parser`__.
+ .. _MoinMoin: http://moinmo.in/
+ __ http://moinmo.in/HelpOnParsers/ReStructuredText
-Tools
-`````
+* Trac_ supports `reStructuredText as alternative wiki markup`__.
-* rstcheck_ Checks syntax of reStructuredText and code blocks nested within
- it. (Using the Sphinx syntax "code-block" for the "code" directive.)
+ __ https://trac.edgewall.org/wiki/WikiRestructuredText
- .. _rstcheck: https://pypi.python.org/pypi/rstcheck
-* restview_ is a viewer for reStructuredText documents.
-
- Pass the name of a ReStructuredText document to restview, and it will
- launch a web server on localhost:random-port and open a web browser. It
- will also watch for changes in that file and automatically reload and
- rerender it. This is very convenient for previewing a document while
- you're editing it.
-
- .. _restview: https://mg.pov.lt/restview/
-
-
Development
-```````````
+-----------
* Sphinx_ extends the ReStructuredText syntax to better support the
- documentation of Software projects (but other documents
- can be written with it too).
+ documentation of Software projects.
-* `Sphinx Extensions`_ allow automatic testing of code snippets,
+ `Sphinx Extensions`_ allow automatic testing of code snippets,
inclusion of docstrings from Python modules (API docs), and more.
-* Trac_, a project management and bug/issue tracking system, supports
- `using reStructuredText
- <https://trac.edgewall.org/wiki/WikiRestructuredText>`__ as an
- alternative to wiki markup.
+ .. _Sphinx extensions: https://www.sphinx-doc.org/en/master/usage/extensions/
+* Trac_, a wiki and issue tracking system, supports
+ `reStructuredText as alternative wiki markup`__.
+ This includes support for TracLinks__ via a `:trac: role`__.
-* PyLit_ provides a bidirectional text <--> code converter for *literate
- programming with reStructuredText*.
+ .. _Trac: https://trac.edgewall.org
+ __ https://trac.edgewall.org/wiki/WikiRestructuredText
+ __ https://trac.edgewall.org/wiki/TracLinks
+ __ https://trac.edgewall.org/wiki/WikiRestructuredTextLinks
-.. _Sphinx extensions: https://www.sphinx-doc.org/en/master/usage/extensions/
-.. _Python documentation: https://docs.python.org/
-.. _Trac: https://trac.edgewall.org
-.. _PyLit: https://codeberg.org/milde/pylit
+* PyLit_ provides a bidirectional text ↔ code converter for Literate
+ Programming with reStructuredText.
+ .. _PyLit: https://codeberg.org/milde/pylit
+
CMS Systems
-```````````
+-----------
-* Plone_ and Zope_ both support reStructuredText markup.
+* Plone_ supports `reStructuredText content`__.
-* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope_"
- application that is complete and ready to install.
+ __ https://6.docs.plone.org/backend/fields.html
+ #restructuredtext-transformation
+* Zope_ (Zope 4 `dropped the ReST shim`__).
+
+ __ https://github.com/zopefoundation/Products.CMFDefault/issues/5
+
.. _Plone: https://plone.org/
.. _Zope: https://www.zope.dev/
-.. _ZReST: https://docutils.sourceforge.io/sandbox/richard/ZReST/
Presentations
-`````````````
+-------------
-* rst2html5_ transform restructuredtext documents to html5 + twitter's
- bootstrap css, deck.js or reveal.js
+There is native support for `slide shows with S5`__.
- .. _rst2html5: https://github.com/marianoguerra/rst2html5
+__ https://docutils.sourceforge.io/docs/user/slide-shows.s5.html
+* InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
+ reStructuredText for markup, although it renders only a subset of rST.
+
+ .. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
+ .. _Inkscape: http://inkscape.org/
+
* landslide_ generates HTML5 slideshows from markdown, ReST, or textile.
.. _landslide: https://github.com/adamzap/landslide
-* `native support for S5 <slide-shows.s5.html>`_.
+* `marianoguerra/rst2html5`__ can produce slides using
+ HTML5 + deck.js, impress.js, or reveal.js.
-* The `PythonPoint interface`_ by Richard Jones produces PDF
- presentations using ReportLabs' PythonPoint.
+ __ https://github.com/marianoguerra/rst2html5
- .. _PythonPoint interface:
- https://docutils.sourceforge.io/sandbox/richard/pythonpoint/
+* Pandoc_ can export to various slide show formats
+ (LaTeX Beamer, PowerPoint, Slidy, S5, ...).
-* rst2beamer_ generates a LaTeX source that uses the `Beamer` document class.
- Can be converted to PDF slides with pdfLaTeX/XeLaTeX/LuaLaTeX.
+* rst2odp_ --- rst to LibreOffice impress.
- .. _rst2beamer: https://docutils.sourceforge.io/sandbox/rst2beamer/
+ .. _rst2odp: https://github.com/mattharrison/rst2odp
-* InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
- reStructuredText for markup, although it renders only a subset of rst.
- .. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
- .. _Inkscape: http://inkscape.org/
+Help / Q&A
+==========
-* rst2outline_ translates a reStructuredText document to a plain text
- outline. This can then be transformed to PowerPoint.
+* Stackoverflow tags `[restructuredtext]`__ and `[docutils]`__.
- .. _rst2outline: https://docutils.sourceforge.io/sandbox/rst2outline/
-
-* Pandoc_ can also be used to produce slides
-
-.. TODO: update with input from
- https://stackoverflow.com/questions/2746692/restructuredtext-tool-support
+ __ https://stackoverflow.com/questions/tagged/restructuredtext
+ __ https://stackoverflow.com/questions/tagged/docutils
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins