Task 8: Advanced Topics

You’ve learned the basics of writing in RST. There is much more to learn! This page contains examples of how to use lesser-known or advanced features.

Embedding HTML

RST extends beyond the markdown basis to include embedding HTML. You might want to make a link with target="_blank" attribute or embed a video using specific HTML.

There are two ways. You can place the directive in the location where you want the HTML to render or use a substitution. Substitutions are a good way to reuse code!

Use the .. raw:: directive to place HTML in your document directly, such as inserting a horizontal rule with a specific width.

.. raw:: html

    <hr width=50 size=10>

Or, you can create a substitution for the <br /> element. Then, you can insert the raw HTML using the |BR| substitution anywhere in your document.

.. |BR| raw:: html

    <br />

Now, I can finally control line breaks! |BR| This text is on the next line.

Just to verify, the
tag works
as
expected.

Reference:

Includes

RST provides the .. include:: directive to read the contents of the referenced file.

.. include:: ../shared/folder/filename.rst

References:

Tables

Tables are useful but can be hard to write in RST using the default method. This guide will show you some options.

Grid and simple tables have their place but are hard to use. Here are two references if you are interested

List Tables are a good option if you need to add content blocks in a cell. Below is the raw markup from the tables with the colored boxes section on Task 3: Note Boxes. The width parameter seems to have no effect. Perhaps it is a problem with the RTD theme.

.. list-table:: Colored Box Types
   :header-rows: 1
   :widths: 25 15 65

   * - Type/Keyword
     - Color/Note
     - Example
   * - danger, error
     - red
     - ``.. danger:: Watch out!``
   * - attention, caution, warning
     - orange
     - ``.. Caution:: Subroutine is not cross-platform.``
   * - hint, important, tip
     - blue
     - ``.. Note:: A generic blue box``
   * - admonition
     - blue
     -
       .. code-block:: rst

           .. admonition:: Custom label

               The contents of the blue box.

CVS Tables are the most convenient if you need to display tabular data. You can see an example from this site on page Step 1: Initialize OpenVPN using Docker. As you can see from the raw RST, you can develop your data in a spreadsheet and then paste do the document directly.

Here is the raw RST.

.. csv-table:: Suggested UDP Ports
  :header: "UPD Port Number", "Description"
  :widths: 1, 10

    22,Secure Shell (SSH)
    53,Domain Name System (DNS)
    123,Network Time Protocol (NTP)
    465,
    554,Real Time Streaming Protocol (RTSP)
    943,
    972,
    995,Post Office Protocol 3 over TLS/SSL  (POP3S)
    1935,Real Time Messaging Protocol (RTMP)
    1234,VLC media player default port for UDP/RTP stream
    10007,VoIP providers (ports 10000-20000)
    11211,Memcached
    3074,Xbox LIVE
    3748,
    5005,Real-time Transport Protocol media data (RTP)
    5730,
    8080,
    17500,Dropbox LanSync Protocol (db-lsp)
    25575,Minecraft

Reference