[PYTHON] Comfortable document life with Docutils and Ruby

Comfortable document life with Docutils and Ruby

It's not a whole new story, but I'll join the advent calendar to organize what I've made earlier.

0. I like reST

First of all I liked setext (structured text). So of course I like reST. Markdown will do most of the work if you don't say the details, but I use reST to make Office files and make adjustments for printing.

Naturally because it is reST

• Python
• docutils

Is used. The installation method is folded. it's simple.

1. Write with rst2html.py + guard anyway

The first step is "quickly turn the preview".

So I use guard, my favorite Ruby tool that is as good as or better than reST. This is a library for monitoring file changes and doing various things, here

1. Hit rst2html.py from guard-shell to generate HTML
2. Open the resulting HTML in a browser and preview it, but monitor the HTML generation and automatically reload with guard-livereload.

I will have you take on the two tasks of. The following three libraries are actually used.

• guard/guard
• guard/guard-shell
• guard/guard-livereload

As a web server, use SimpleHTTPServer of Python or WEBrick of Ruby as appropriate.

• Prepare the following Gemfile and Guard
• Launch guard
• Any content is fine, so generate HTML and capture with livereload
• All you have to do is edit the .rst file

is.

reST-writing environment with realtime HTML-preview — Gist

2. Generate and finish the odt with rst2odt.py + rake

If there is no problem with the content in the preview, this time my work

wtnabe/rst2odt_stylesheet

To use. Git clone this and rename the target rst file to sample.rst. What this guy can do

• Hit rst2odt.py to generate an odt file from reST
• Compile the stylesheet used when generating the odt file
• You can also adjust the stylesheet yourself in XML
• Open the odt file created by the open command

is. Unfortunately, both the reST file and the odt file have been left untouched for two years with the name sample, and I only use the Mac, thinking that open should use a library that abstracts this. It is as it is because it is not.

After opening the odt file, adjust the style for printing, and if you notice any mistakes at this stage, modify the rst file each time.

rake open

It will be a flow to do.

Finally, I think it's easier to share if you export the PDF from LibreOffice (OpenOffice.org).

3. Summary

It's not very unified, and my rst2odt_stylesheet rake task isn't very complete, but at least I think it's a lot easier to write a document than suddenly writing it in Word.

reST is a very versatile notation because it embodies one of the features of its predecessor, setext, "it is not unnatural to embed it in an email as it is", and the notation of table is also organized. Also, if you convert it to odt in this way and then export it to PDF, the sentence structure will be reflected in the final PDF, so even long documents will be easier to read.

Both cats and scoops are Markdown these days, so why not try writing a document with reST?

What is regrettable is that the processing system is not available in each language like Markdown. Since it is practically for Python only, it can be used with Trac, but I think it is difficult to use it from Redmine. I wonder if anyone will transplant it (flickering)