ReStructuredText under Windows

By Sep 22, 2015

Description:

ReStructuredText is a lightweight markup language and a Python script converts text to HTML. Here we indicate how to call this script in PowerShell and give some examples.

Preferencesoft

ReStructuredText is a lightweight markup language part of Docutils, a package of Python. Such markup language is very useful for automatic Web page creation and the seizure of contents of Web page by different authors. In this page, we are going to see how to use reStructuredText to convert a text file to the HTML format and insert it in a template HTML page.

Installing ReStructuredText

You need to first install the Python language on your machine. Make sure that the command py.exe (or python.exe) is in your PATH variable. If this is not the case, look for environment variables in your system and add the path up to py.exe. If you do not add it, you need to specify the full path every time. In my case, the full path is

C:\Users\preferencesoft\AppData\Local\Programs\Python\Python35

Open a PowerShell windows and install Docutils with the command:

C:\Users\preferencesoft\AppData\Local\Programs\Python\Python35\Scripts\pip3.5.exe install docutils

Then check the presence of the script rst2html.py in the directory:

C:\Users\preferencesoft\AppData\Local\Programs\Python\Python35\Scripts

Try without further delay this script for an example. With notepad, type or copy the following text and save it in MyText.txt:

Section Header
==============
 
Subsection Header
-----------------
 
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
1) Sed non risus.
2) Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.
   a) Cras elementum ultrices diam. Maecenas ligula massa, varius a, semper congue, euismod non, mi.
   b) Proin porttitor, orci nec nonummy molestie, enim est eleifend mi, non fermentum diam nisl sit amet erat.
3) Duis semper. Duis arcu massa, scelerisque vitae, consequat in, pretium a, enim. Pellentesque congue.
 
Ut in risus volutpat libero pharetra tempor. Cras vestibulum bibendum augue. Praesent egestas leo in pede.
 
Praesent blandit odio eu enim. Pellentesque sed dui ut augue blandit sodales. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Aliquam nibh. Mauris ac mauris sed pede pellentesque fermentum. Maecenas adipiscing ante non diam sodales hendrerit.

Now in PowerShell, run the command:

py.exe C:\Users\prefe\AppData\Local\Programs\Python\Python35\Scripts\rst2html.py .\MyText.txt

If no error was detected, you must scroll to display the HTML corresponding to your text.

You can direct the output to a text file:

py.exe C:\Users\prefe\AppData\Local\Programs\Python\Python35\Scripts\rst2html.py.\MyText.txt > .\MyText.html

Let's create a script rst.ps1 which apply Python rst2html.py script to a file_name.txt text file and place the output file file_name.html in the same directory as the original file.

Param(
  [string]$file_name
)
$html_ext = ".html"
 
if ($file_name[0] -eq '.')
{
   $fn = $file_name.SubString(2, $file_name.Length - 2)
}
else
{
   $fn = $file_name
}
# get the current script path
$csp = Split-Path -parent $MyInvocation.MyCommand.Definition
# $f source file
$f = $csp + "\" + $fn
$h = [System.IO.Path]::GetFileName($f)
$p = $f.SubString(0, $f.Length-$h.Length)
$f = $p + $h
$h = [System.IO.Path]::GetFileNameWithoutExtension($h)
# $d destination file
$d = $p + $h + $html_ext
py.exe  C:\Users\preferencesoft\AppData\Local\Programs\Python\Python35\Scripts\rst2html.py $f > $d

Note that the style of the page is built into the HTML file created. You will see when viewing the HTML file with your browser that style lack of contrast. It is possible to customize its style by retrieving the html4css1.css file present in a subdirectory of the Python and bring his personal touch. So rst2html.py binds the HTML page to your style sheet, you can use the option --stylesheet-path = <file[,file,...]>

To easily insert the HTML file in a template, I added to my script instructions that keep only the part strictly included between <body> and </body>.

I take this opportunity to remove an error caused by the rest2html.py script when it encounters a symbol: in certain blocks of code.

This is the job:

Param(
  [string]$file_name
)
$ext =".html"
 
$g = Split-Path -parent $MyInvocation.MyCommand.Definition
if ($file_name[0] -eq '.') { $fn = $file_name.SubString(2, $file_name.Length - 2) } else { $fn =$file_name }
$f = $g+ "\" + $fn
$h = [System.IO.Path]::GetFileName($f)
$p = $f.SubString(0, $f.Length-$h.Length)
$f = $p + $h
$h = [System.IO.Path]::GetFileNameWithoutExtension($h)
$d = $p + $h + $ext
$res = py.exe  C:\Users\preferencesoft\AppData\Local\Programs\Python\Python35\Scripts\rst2html.py --initial-header-level=1 --no-doc-title --stylesheet=C:\Users\preferencesoft\Documents\ReSt\input\html4css1.css --link-stylesheet $f
$between = $FALSE
$firstline = $TRUE
$content=""
foreach ($line in $res)
{
    if (-not $firstline)
    {
        $content = $content + "`r`n"
    }
    if ($line.IndexOf("<body>") -ge 0)
    {
        $l = $line.SubString($line.IndexOf("<body>")+6)
        $l = $l  -replace("<span class=""error"">", "<span class=""punctuation"">")
        $content = $content + $l
        $between = $TRUE
        $firstline = $FALSE
    }
    else
    {
        if ($line.IndexOf("</body>") -ge 0)
        {
            $l = $line.SubString(0, $line.IndexOf("</body>"))
            $l = $l  -replace("<span class=""error"">", "<span class=""punctuation"">")
            $content = $content + $l
            $between = $FALSE
            $firstline = $FALSE
        }
        else
        {
            if ($between)
            {
                $l = $line  -replace("<span class=""error"">", "<span class=""punctuation"">")
                $content = $content + $l
                $firstline = $FALSE
            }
        }
    }
}
$content > $d

Python

Categories

Share

Follow


KodFor Privacy Policy