Strona używa cookies (ciasteczek). Dowiedz się więcej o celu ich używania i zmianach ustawień. Korzystając ze strony wyrażasz zgodę na używanie cookies, zgodnie z aktualnymi ustawieniami przeglądarki.    X

reStructuredText

Zainspirowany dyskusją z blogerem Orlando postanowiłem przyjrzeć się bliżej językowi znaczników reStructuredText, będącego komponentem systemu Docutils, wykorzystywanego m.in. przez generator dokumentacji Sphinx. Dyskusja dotyczyła modułu rst2odp, który umożliwia konwersję pliku rst do pliku prezentacji multimedialnej odp, którą można otworzyć w OpenOffice lub MS Office.

Ten wpis będzie się składał z dwóch części. Pierwsza dotyczyć będzie jednego ze sposobów instalacji pakietów dla języka Python, a druga konwersji plików rst na inne formaty.

INSTALACJA PAKIETÓW

Instalacja dodatkowych modułów dla języka Python może odbywać się na kilka sposobów:

1. Kompilacja ze źródeł
2. Instalacja pakietów binarnych (np. z repozytorium dystrybucji Linuksowych)
3. Instalacja odpowiednio przygotowanych dla systemu Windows plików exe
4. Instalacja przy pomocy narzędzia easy_install

Tym razem wykorzystamy narzędzie easy_install. Zasada działania easy_install przypomina np. znany z Ubuntu system zarządzania pakietami APT. Sposób instalacji pakietów przy pomocy easy_install zostanie omówiony na przykładzie Windowsa, choć w systemach klasy Unix odbywa się to bardzo podobnie.

Aby móc skorzystać z easy_install należy zainstalować pakiet setuptools.

Po zainstalowaniu uruchamiamy wiersz poleceń, przechodzimy do katalogu Scripts

cd C:\Python26\Scripts

i przy pomocy narzędzia easy_install instalujemy pozostałe wymagane w dalszej części opisu moduły:

easy_install docutils easy_install Pygments easy_install PIL

Następnie instalujemy moduły do konwersji plików rst na wybrany format wyjściowy

easy_install rst2pdf easy_install rst2beamer easy_install rst2odp

rst2pdf umożliwia konwersję pliku rst do PDF-a, rst2beamer do pliku tex, a rst2odp do pliku prezentacji OpenDocument.

Dygresja:

Plik tex uzyskany przy pomocy rst2beamer jest plikiem prezentacji w systemie LaTeX z klasą Beamer. Patrz: dobraprezentacja.
PIL (Python Imaging Library) jest biblioteką do zaawansowanej obsługi obrazów dla języka Python. Patrz: Styl retro.

Lista paczek dla Pythona znajduje się na stronie PyPi.

KONWERSJA RST DO WYBRANEGO FORMATU WYJŚCIOWEGO

Po zainstalowaniu powyższych pakietów mamy możliwość skorzystania z kilku narzędzi do konwersji plików reStructuredText na wybrany format plików wyjściowych, np.: html, tex, pdf, odt, odp.

reStructuredText charakteryzuje się bardzo prostą i czytelną składnią. Mimo, że przy tworzeniu dokumentu posługujemy się "zwykłym tekstem", dokumenty tworzone są zgodnie z zasadą what-you-see-is-what-you-get, a nie tak jak w przypadku np. LaTeX-a what-you-see-is-what-you-mean. Dzięki temu możemy w prosty i przyjemny sposób otrzymać ładnie sformatowane pliki PDF, html itd.

Ze składnią reStructuredText można zapoznać się na stronie quickref. Efekt działania można obserwować korzystając z renderera online reST.

Krótki opis w języku polskim oraz przykłady znajdziemy na stronie cs.put.poznan.pl.

Zawartość strony z przykładem first.txt zapisujemy w pliku example.rst np. na dysku D. Do tego celu tradycyjnie polecam edytor gVim, który świetnie radzi sobie z kolorowaniem składni. Można oczywiście skorzystać z dowolnego edytora / notatnika.

Ciekawym edytorem dostępnym dla systemu Windows i Linux jest reStructuredText Editor.

Można także skorzystać z edytora online zapewniającego podgląd w czasie rzeczywistym.

Uruchamiamy wiersz polecenia (cmd) i przechodzimy do katalogu Scripts

cd C:\Python26\Scripts

Aby uzyskać pomoc na temat wybranego konwertera używamy opcji --help, np.

rst2pdf --help

Skonwertujmy zatem zapisany na dysku D plik example.rst do różnych plików wyjściowych.

HTML

C:\Python26\Scripts>rst2html.py D:\example.rst D:\example.html

example.html

PDF

C:\Python26\Scripts>rst2pdf D:\example.rst --language="pl" --output=D:\example.pdf

example.pdf

LaTeX

C:\Python26\Scripts>rst2latex.py --output-encoding=cp1250 D:\example.rst D:\example_tex.tex

gdzie

--output-encoding=cp1250

jest stroną kodową używaną przez system Microsoft Windows do reprezentacji tekstów w językach środkowoeuropejskich.

example_tex.tex, po skompilowaniu w LaTeX-u otrzymujemy example_tex.pdf

LaTeX Beamer

C:\Python26\Scripts>rst2beamer --output-encoding=cp1250 D:\example.rst D:\example_beamer.tex

W ten sposób otrzymujemy gotowy plik tex z prezentacją, do którego możemy dodać szczegóły w postaci tytułu, autora itd. oraz zmodyfikować temat graficzny itp. Opcje te można też dodać jako parametry przy kompilacji. Patrz: rst2beamer --help

example_beamer.tex, po skompilowaniu w LaTeX-u otrzymujemy example_beamer.pdf

ODT

C:\Python26\Scripts>rst2odt.py D:\example.rst D:\example.odt

example.odt

ODP

C:\Python26\Scripts>C:\Python26\python.exe rst2odp D:\example.rst D:\example.odp

niestety kończy się komunikatem o błędzie

WindowsError: [Error 32] Proces nie mo¬e uzyskaŠ dostŕpu do pliku, poniewa¬ jest on u¬ywany przez inny proces: 'c:\\users\\krystian\\appdata\\local\\temp\\tmpuw5sks' Exiting due to error. Use "--traceback" to diagnose. Please report errors to . Include "--traceback" output, Docutils version (0.7 [release]), Python version (2.6.6), your OS type & version, and the command line used.

Zobacz również: Prezentacja wideo na temat reStructuredText 

Komentarze

0 nowych
Orlando   3 #1 07.10.2010 19:59

A zatem RST2ODP jest jednak mocno betowata. Szkoda. A propos - skąd pociągnąć ten edytor? W podlinkowanym blogu jest taki bajzel, że nie mogę go znaleźć.

iluzion   5 #2 07.10.2010 20:54

@Orlando

Być może coś źle robimy z tym RST2ODP, ale skoro podobne narzędzia wchodzące w skład Docutils działają prawidłowo to może być wina RST2ODP (przynajmniej pod Windowsem).

Jeśli chodzi o edytor to podałem go jako ciekawostkę. Sposób instalacji jest podany na blogu, ale nie wygląda to elegancko:

"First, you need to get SVN, Python 2.x (minimum 2.4), SetupTools, PyQt4 and NumPy and install them. (I’m not 100% sure, but MinGW might be needed too on Windows.)"

Jest to raczej edytor, który ma szansę znaleźć się w dystrybucji naukowej Enthought, o której kiedyś wspominałem na blogu. Prościej jest skorzystać z gVima czy innego edytora.

Spróbuj raczej edytora online, który działa na podobnej zasadzie (zapewnia "podgląd w czasie rzeczywistym")

http://rst.ninjs.org/

Gdy wszystko jest ok, wystarczy tekst skompilować do wybranego formatu pliku.

Orlando   3 #3 09.11.2010 14:08

Mam mały problem z RST:
Potrzebuję listy zagnieżdżone w innej liście:
1. cośtam
a) cośtam
b) cos tam
2. coś tam
a) coś tam
b) coś tam

i robię to wcinając tabulatorem listy zagnieżdżone. Jednak otrzymuję:
1. coś tam
a) coś tam
b) coś tam
2. coś tam
c) coś tam
d) coś tam

Czyli wewnętrzna lista nie startuje od początku. Co robię źle?

iluzion   5 #4 09.11.2010 22:25

Zależy w jaki sposób tworzysz listę. Wcięcia w RST są istotne, podobnie jak w Pythonie, a może nawet ważniejsze. Ważne jest, aby były równe dla danego pakietu (bloku tekstu). Poza tym ważne są puste linie (bez spacji czy tabulatorów!), które oddzielają poszczególne pakiety, m.in. fragmenty kodu. I tak np. chcąc wstawić kod wpisujemy podwójny dwukropek ::



Podobnie postępujemy z listami:
1. Punkt pierwszy

a) Przykład 1a
b) Przykład 1b

2. Punkt drugi

a) Przykład 2a
b) Przykład 2b


Nie wiem dlaczego w Twoim przypadku lista nie startuje od początku. Może używasz znaku automatycznej numeracji (#)?

Polecam przykłady:

http://sphinx.pocoo.org/rest.html
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

iluzion   5 #5 09.11.2010 22:29

No ładnie... serwis "wycina" wszystko co jest zapisane pomiędzy znacznikami "" jak w html, a w nich zawarłem komentarze odnośnie wcięć i pustych linii. Mam nadzieję, że strony z odnośników wszystko wyjaśnią.

Orlando   3 #6 10.11.2010 13:46

Właśnie robiłem, jak to opisano, tylko efekt był nieoczekiwany. Przy konwersji na HTML sublisty były ujmowane z znacznik blocquote, a w OpenOffice pliki ODT nie przyjmowały formatowania a. b. itp, tylko 1. 2. To pewnie niedoskonałość narzędzi. Będę dalej testował, chociaż troszkę jestem rozczarowany docutils.

Orlando   3 #7 16.11.2010 12:31

Wracam do moich problemów. Jednak chciałbym korzystać z RST2ODP i mam problem techniczny. RST2ODP uparcie twierdzi, że nie mam zainstalowanej biblioteki PIL. Mam i na wszelki wypadek zainstalowałem ponownie za pomocą easy_install wersję 1.1.7. Nie pomogło. Podejrzewam, że gdzieś w plikach konfiguracyjnych trzeba coś dostukać, ale nie wiem gdzie. Nie dzieje się to automagicznie, jak mi się marzyło. Pomożecie?

iluzion   5 #8 16.11.2010 18:28

Wpisz w IDLE: import PIL
Jeśli otrzymasz komunikat "ImportError: No module named PIL" to znaczy, że nie jest poprawnie zainstalowany.

Ja mam PIL doinstalowany z exe i rst2odp nie narzeka na jego brak, ale mam za to inny błąd. Nadal nie wiem gdzie leży przyczyna. Proponuję zapytać autora rst2odp.

Scottie33   4 #9 14.02.2012 19:21

@iluzion:
Dzięki za ten tutorial! Świetnie, rzeczowo i przede wszystkim super intuicyjnie to wszystko opisałeś. Powinieneś częściej pisać. Serio!! :) Może w przyszłości jakiś wpis o micro web-frameworkach dla Pythona? Nie wszyscy (np. ja) potrzebują tej kobyły Django...

PS Jakby ktoś pytał, to dla Pythona 3.x zamiast pakietu "setuptools" trzeba użyć "distribute".