How to convert reStructuredText to plain text

Question

I plan to use reStructuredText to write documentation with the main purpose of generating some nice HTML pages. For this I use the docutils rst2html.py tool.

However, I may also need to present the documentation in nice plain text format, that is without the reStructuredText markup, and where paragraph wrapping and similar nice formatting is still performed on the text output. But, there is no rst2txt.py tool in the docutils.

Is there a way to convert reStructuredText to nice plain text format, maybe with use of special options to docutils ?

Comprehensible

I think reStructuredText is that “nice plain text format“ you are looking for in the first place! – Jeremiah

Answer 1

Sphinx has a TextBuilder for txt output format. Just tried it and it seems to do what you are looking for.

However, it might be a little outdated because it is not in the default Makefile. But it worked well on my fairly complex documentation (150 pdf pages). To use it, just add the following target to it:

text:
    $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
    @echo
    @echo "Build finished."

Also, keep in mind that Sphinx implements only a subset of the rst specs.

Embree

Thanks Thoriann, I was able to get this to work through the makefile. I would also like to use the TextBuilder directly from Python, but I could not find any documentation for this. Do you know where to find documentation for TextBuilder class, or a short example showing how to use it from Python ? Best regards, Morten – Comprehensible

I don't know of any documentation regarding this, either. You can look in cmdline.py from the Sphinx source code for an example. Seems doable, if you really want that. – Embree

@Thoriann: Sphinx can only render a subset of rst? Why do you think that? – Parhe

Answer 2

I have also seen this done by rendering to html using rst2html, then converting the html to plain text by using a command-line html browser, such as:

• lynx http://lynx.browser.org
• links http://links.sourceforge.net
• w3m http://w3m.sourceforge.net
• elinks http://elinks.or.cz

Each of these browsers has a command-line switch or similar to render its output to a .txt file, so you could create a two line script called 'rst2txt', something like:

rst2html docs.rst docs.html
lynx -dump docs.html > docs.txt

Attendant

This one worked best for me. I think the 'right' thing is to write an XLST stylesheet to convert to txt and maybe org-mode – Illjudged