Task 3: Note Boxes

RST Colored Boxes

Colored boxes provide a way to emphasize blocks of text using blue, green, orange/yellow, or red using the directive .. box-type::.

They all use the same syntax using a different keyword:

Colored Box Types

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

.. admonition:: Custom label

    The contents of the blue box.

Tip

  • Colored boxes act as text blocks because anything indented four spaces stay in the text box.

  • For example, this list!

Note

RST lines should be 80 characters long

As a final thought

You don’t have to use the note title for a blue box. Instead, use your own text!

RST for the above boxes
.. tip::

    * Colored boxes act as paragraphs because anything indented
      four spaces stay in the text box.
    * For example, this list!

.. note:: RST lines should be 80 characters long

.. admonition:: As a final thought

    You don't have to use *note* for a blue box. Instead, use
    your own title!

Task

Task 3: Add text to Installing Sphinx to learn how to use a note box.

  • Use inline styles and hyperlinks appropriately.

  • Add a note about using other distributions

    Note

    A default note has this style. There are other default boxes, such as hint and warning.


Text to add

The Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/installation.html>
provides instructions for Debian/Ubuntu (apt), RHEL/CentOS (yum),
and MacOS (homebrew). This guide will uses the ``apt`` package manager.

Unfortunately, the apt package manager for Debian has an old version of
Sphinx (Sphinx 1.8.4). It works, but PyPI has the latest version of
Sphinx <https://pypi.org/project/Sphinx/>. Therefore, this guide
shows to install Sphinx using both ``apt`` and ``pip3``.

Note: Other distributions are supported using pip, such as Alpine Linux.
However, additional knowledge is required to install prerequisites for
specific Python packages.