ReStructuredText

reStructuredText
Rozszerzenia pliku	`.rst`
Data opracowania	2001-06-02^[1]
Ostatnia wersja	0.16 (2020-01-12)^[2]
Typ	język znaczników
Strona internetowa

reStructuredText – język znaczników oraz analizator składniowy, przeznaczony do szybkiego tworzenia prostych stron internetowych, samodzielnych dokumentów i dokumentacji technicznej^[3].

reStructuredText jako język znaczników, wprowadzanych zwykłym tekstem (ang. plaintext), wykorzystuje proste i intuicyjne konstrukcje do wskazania struktury oraz formatowania dokumentu. Te konstrukcje i znaczniki są równie łatwe do odczytania w formach surowych (ang. raw), jak i przetworzonych (np. do docelowych formatów: HTML, PDF, LaTeX i innych)^[4].

Parser reStructuredText wchodzi w skład większego systemu Docutils^[3] w języku programowania Python, którego celem jest stworzenie zestawu narzędzi do generowania dokumentacji kodu źródłowego dla Pythona, podobnego do Javadoc dla Javy lub POD dla Perla.

reStructuredText jest czasami skracany jako RST, ReST lub reST. Może to być źródłem zamieszania oraz mylnie wskazywać na niepowiązaną z reStructuredText technologią Representational State Transfer (REST).

Zastosowanie

reStructuredText jest popularnym i powszechnie używanym językiem do tworzenia dokumentacji technicznej, na przykład w dokumentacji bibliotek, jak i samego języka Python^[5]. Jednakże nadaje się również do tworzenia szerokiego zakresu innych, niekoniecznie technicznych tekstów.

reStructuredText jest podstawowym komponentem pythonowego systemu generowania dokumentacji Sphinx.

System zarządzania projektami i śledzenia błędów Trac wspiera reStructuredText oraz umożliwia wykorzystanie go jako alternatywę dla wikitekstu.

Przykłady składni

Nagłówki i sekcje

1. Rozdział pierwszy
====================

1.1. Podrozdział
----------------

1.1.1. Podrozdział
~~~~~~~~~~~~~~~~~~

1.2. Podrozdział
----------------

2. Rozdział drugi
=================

Listy

Listy numerowane:

1) Pierwszy element listy

2) Drugi element listy

   a) Sub-element

      i) Sub-sub element

3) Trzeci element listy

#. Kolejny (czwarty) element (lista auto-numerowana)

Listy nienumerowane:

- Pierwszy element listy

- Drugi element listy

  - Sub-element

- Trzeci element listy

Definicje

Pojęcie1 
  Definicja pierwsza

Pojęcie2 
  Definicja druga

Formatowanie tekstu

*emfaza*
**silna emfaza**
``tekst o stałej szerokości znaków``

Ilustracje

.. image:: /scieżka/do/pliku/obrazek.jpg

Odnośniki

Linki nazwane:

Przykład zdania z odnośnikami do Wikipedii_ i strony `Linux kernel archive`_.

.. _Wikipedii: http://www.wikipedia.org/
.. _Linux kernel archive: http://www.kernel.org/

Linki nienazwane (anonimowe):

Przykład zdania z `anonimowym odnośnikiem do strony domowej Pythona`__.
 
__ http://www.python.org/

Odnośniki umieszczać można również jako osadzone umieszczając link między nawiasami ostrokątnymi (< >).

Ekwiwalentny zapis powyższego zdania z osadzonym odnośnikiem do strony domowej `Pythona <http://www.python.org/>`_.

Linki wewnętrzne:

Wewnętrzny link do innej części dokumentu, przykład_.

.. _przykład:

To jest przykład elementu docelowego dla linku wewnętrznego.

Komentarze

.. Ten tekst nie zostanie wyświetlony

lub

.. 
   Ten tekst
   również nie zostanie wyświetlony

Przypisy

↑ reStructuredText Project History. [dostęp 2012-08-20]. (ang.).
↑ Docutils Release Notes. [dostęp 2020-11-12]. (ang.).
↑ ^a ^b reStructuredText – Markup Syntax and Parser Component of Docutils. [dostęp 2012-08-20]. (ang.).
↑ reStructuredText Markup Specification. 2012-01-03. [dostęp 2012-08-20]. (ang.).
↑ PEP 287 -- reStructuredText Docstring Format. [dostęp 2012-09-01]. (ang.).