Kivy - reStructuredText

reStructuredText is a file format for a text file containing data used primarily in the Python for technical documentation. The file usually has a ".rst" extension.

  • reStructuredText is a part of the DocUtils project, and its main purpose is to provide a set of tools for Python that are similar to Javadoc for Java. Written by David Goodger, its earliest version was released in 2001, the latest being in 2019.

  • reStructuredText can be considered as a lightweight markup language, with lot of similarities with MarkDown syntax. It is being used as a core component of Python's Sphinx document generation system.

Kivy provides reStructuredText document renderer in the form of RstDocument class defined in the "kivy.uix.rst" module.

from kivy.uix.rst import RstDocument
doc = RstDocument(**kwargs)

Formatting reStructuredText

  • Paragraph − A chunk of text that is separated by blank lines (one is enough). Paragraphs must have the same indentation.

  • Bold − Characters between two asterisks (example:**Hello**)

  • Italics − characters between single asterisks(ex: *world*)

  • Enumerated list − Start a line off with a number or letter followed by a period ".", right bracket ")" or surrounded by brackets "( )". For example −

1. Python
2. Java
3. C++

  • Bulleted list − start the line off with a bullet point character - either "-", "+" or "*"

  • Sections − These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "-----", equals "======"

  • Images − To include an image in your document, you use the the image directive. For example −

.. image:: kivi-logo.png

Example

Following text is formatted as per the reStructuredText syntax. Save the following text as index.rst −

================
Welcome to Kivy
================
Welcome to Kivy's documentation. **Kivy** is an open source software library for the rapid development of applications equipped with novel user interfaces, such as multi-touch apps.
With Kivy, you can create apps that run on:

* Desktop computers: macOS, Linux, *BSD Unix, Windows.
* iOS devices: iPad, iPhone.
* Android devices: tablets, phones.


-------------------
Virtual environment
-------------------
Create the virtual environment named kivy_venv in your current directory_::

   python -m virtualenv kivy_venv
   
Activate the *virtual environment*.

For Windows default CMD, in the command line do_::
   kivy_venv\Scripts\activate
   
Your terminal should now preface the path with something like (kivy_venv), indicating that the kivy_venv environment is active.
If it doesn't say that, the virtual environment is not active and the following won't work.

Install Kivy
------------
The simplest is to install the current stable version of kivy is to use pip_::

   python -m pip install "kivy[base]" kivy_examples

Let us write a program to render this reStructuredText document in Kivy application. We put a RstDocument widget in a grid layout with a single column. Set the source property of this object to the RST file that we have created.

from kivy.app import App
from kivy.uix.rst import RstDocument
from kivy.uix.gridlayout import GridLayout
from kivy.core.window import Window

Window.size = (720,400)

class rstdemoapp(App):
   def build(self):
      grid=GridLayout(cols=1)
      doc = RstDocument(source="index.rst")
      grid.add_widget(doc)
      return grid
rstdemoapp().run()

Output

Run the above code. The RST document will be displayed as per the formatting syntax explained above.

Kivy Restructured Text
Advertisements