How to render .rst files in a markdown or html format?

Question

In many django projects, in the docs directory I can see *.rst files:

Is there a standard, simple, or common way of rendering and displaying these, instead of viewing their contents as plain text?

Is it possible to generate HTML from the .rst files?

Can you please edit the description to expand on the "without using a text editor of course"? That would seem to be a good way, and your reasons for rejecting it aren't clear. — bignose, Apr 05 '10 at 23:23
Edits have been made to try to salvage this question from being opinion-based. Is there a process for removing the `opinion-based` flag now? — EL_DON, Oct 12 '20 at 22:27

score 40 · Answer 1 · answered Apr 05 '10 at 22:47

40

.rst files are ReStructuredText format. They look like text files, but can be rendered into HTML with the Python docutils package.

answered Apr 05 '10 at 22:47

Mike DeSimone

41,631
10
72
96

3

any steps of how to do that? – liang May 01 '18 at 10:27
The docutils package installs a program called `rst2html.py`. Use that. – Mike DeSimone Jun 02 '18 at 14:00
1

@liang `rst2html.py FOO.rst > FOO.html` – Amir Jul 03 '20 at 21:30
1

I prefer this approach because it doesn't launch any web servers. I redirect output to `w3m` like: `rst2html.py somefile.rst | w3m -T text/html`. – Alireza Mohamadi Dec 04 '20 at 19:55

score 25 · Answer 2 · answered Nov 22 '14 at 23:16

As zjk says, you can use restview:

restview is available from the Python Package Index: http://pypi.python.org/pypi/restview. You can also pip install restview.

Here is what I did to test it out using a virtual environment:

mkdir restview
cd restview/
virtualenv-2.7 venv   # The second system I used just used 'virtualenv venv'
./venv/bin/pip install restview
./venv/bin/restview ~/path/MANUAL.rst

This launched a web server and opened the documentation page in my browser.

Note: I only used virtualenv because I don't like installing things globally. It may be overkill for many others, but I also have better luck with these one-off environemnets. When I tried pip install restview on an Ubuntu 14.04 VM it failed, whereas the approach above worked like a charm for me on that system as well as this one.

oh, I didn't know I can use virtualenv this way too. thanks! — Chan Kim, Dec 06 '20 at 02:24

score 11 · Answer 3 · answered Aug 08 '11 at 06:20

11

Try restview

answered Aug 08 '11 at 06:20

zjk

2,043
3
28
45

17

Whilst this may theoretically answer the question, [it would be preferable](http://meta.stackexchange.com/q/8259) to include the essential parts of the answer here, and provide the link for reference. – Bill the Lizard Aug 08 '11 at 12:31

How to render .rst files in a markdown or html format?

3 Answers3