Quick search

reStructuredText renderer

New in version 1.1.0.

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system.

Warning

This widget is highly experimental. The whole styling and implementation are not stable until this warning has been removed.

Usage with Text

text = """
.. _top:

Hello world
===========

This is an **emphased text**, some ``interpreted text``.
And this is a reference to top_::

    $ print "Hello world"

"""
document = RstDocument(text=text)

The rendering will output:

_images/rstdocument.png

Usage with Source

You can also render a rst file by using RstDocument.source:

document = RstDocument(source='index.rst')

You can reference other documents with the role :doc:. For example, in the document index.rst you can write:

Go to my next document: :doc:`moreinfo.rst`

It will generate a link that, when clicked, the document moreinfo.rst will be loaded.

class kivy.uix.rst.RstDocument(**kwargs)

Bases: kivy.uix.scrollview.ScrollView

Base widget used to store an Rst document. See module documentation for more information.

colors

Dictionary of all the colors used in the RST rendering.

Warning

This dictionary is needs special handling. You also need to call RstDocument.render() if you change them after loading.

colors is a DictProperty.

document_root

Root path where :doc: will search any rst document. If no path is given, then it will use the directory of the first loaded source.

document_root is a StringProperty, default to None.

goto(ref, *largs)

Scroll to the reference. If it’s not found, nothing will be done.

For this text:

.. _myref:

This is something I always wanted.

You can do:

from kivy.clock import Clock
from functools import partial

doc = RstDocument(...)
Clock.schedule_once(partial(doc.goto, 'myref'), 0.1)

Note

It is preferable to delay the call of the goto if you just loaded the document, because the layout might not be finished, or if the size of the RstDocument is not fixed yet, then the calculation of the scrolling would be wrong.

However, you can do a direct call if the document is already loaded.

New in version 1.3.0.

preload(filename)

Preload a rst file to get its toctree, and its title.

The result will be stored in toctrees with the filename as key.

render()

Force document rendering.

resolve_path(filename)

Get the path for this filename. If the filename doesn’t exist, it return the document_root + filename.

show_errors

Indicate if RST parsers errors must be shown on the screen or not.

show_errors is a BooleanProperty, default to False

source

Filename of the RST document.

source is a StringProperty, default to None.

text

RST markup text of the document.

text is a StringProperty, default to None.

title

Title of the current document.

title is a StringProperty, default to ‘’ in read-only.

toctrees

Toctree of all loaded or preloaded documents. This dictionary is filled when a rst document is explicitly loaded, or where preload() has been called.

If the document has no filename, e.g., when the document is loaded from a text file, the key will be ‘’.

toctrees is a DictProperty, default to {}.