Task 3: Note Boxes

Table of Contents

• Task 3: Note Boxes

  • RST Colored Boxes

    • References

  • Task

  • Text to add

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!

References

• https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html

• https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#colored-boxes-note-seealso-todo-and-warnings

• https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions

---

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.