reStructuredText към html. Скрипт.

Днес написах един доста прост скрипт който конвертира .rst(reStructuredText) файлове в html. Може и да съм блогвал за ResT преди, но ако не съм, този пост ще е малко по подробен от всичко което може би съм споменавал.

Какво е Rest? Това е markup език, но доста по прост от html, в повечето случаи се използва за писане на документация, която после се конвертира в html,pdf,LaTeX и др. формати. Основното предимство на този език е че е мнооого прост. Мога да ви науча на повечето от важните неща на няколко реда, ето един .rst файл, да речем test.rst:

========

Заглавие

========



1. Първа точка



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст::





    def some_code(param):

        for x in param:

            do_someshit()





a) това е под хараграф



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,



b) това е друг под параграф:



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,



2. Втора точка



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

този файл дори има и грешка при подточка а) :D
Както виждате заглавието е обградено от горе и от долу със '=', което го прави голямо заглавие, подзаглавията, макар и че няма такива в този пример, са само подчертани. За заглавия и подзаглавия може да се използват всякакви знаци('#','@','=','$','-' и др.) Важното е заглавието да е покрито от началото си до края със еднаквите знаци от горе и от долу(няма да работи ако са по къси от заглавието, или ако имат различна дължина), а подзаглавията трябва да са подчертани.

Както може би предполагате, точките и подточките са си част от Markup-а на езика и те дефинират подпараграфи и списъци. А самите параграфи са просто блокове от текст със празни пространства от горе и от долу. Блоковете с код са отместени на дясно, и на предния параграф има двойни двоеточия(::) които по късно стават на единична двоеточие(:). Сега вече знаете достатъчно reStructuredText за да пишете добри документи, за повече подробности посетете сайта им.

Сега, за да ги конвертирате в html или друг формат ви трябва някакъв инструмент, един от най добрите инструменти е Sphinx. Това е изключително мощен инструмент, с чиято помощ е генерирана документацията на python. За моя скрипт аз използвах модула docutils. Ето скриптът:

#!/usr/bin/env python

# -*- coding: utf-8 -*-



#convert a bunch of RestructuredText files to html

#version 0.3.14



from docutils.core import publish_string

import sys



def read_file(f):

    """reads the file, returns a string"""

    i=open(f,'r')

    z=i.read()

    i.close()

    return z



def converter(rst):

    """turns the rst formated string in to html and returns is as a str"""

    return publish_string(source=rst,writer_name='html')



def write_to_file(name,content):

    """writes the html string to a file"""

    name=name[:-4]+'.html'  #turn .rst into .html

    o=open(name,'w')

    o.write(content)

    o.close()



if __name__=='__main__':

    for f in sys.argv[1:]:

        i=read_file(f)

        i=converter(i)

        write_to_file(name=f,content=i)

ако искате да го използвате, просто го запишете в някакъв файл и му дайте права за изпълнение, и го стартирайте:

$./фяйл списък с файлове за конвертиране

всеки файл ще бъде конвертиран във съответния html файл със същото име(но различно разширение, от .rst на .html) Ето изходът от горния rest файл:

Заглавие





Първа точка



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст:


def some_code(param):

    for x in param:

        do_someshit()





това е под хараграф



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,



това е друг под параграф:



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,



Втора точка



Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Това е параграф, той е просто текст,Това е параграф, той е просто текст,

Надявам се този пост да е бил полезен до някъде :D