Task 2: Paragraph and Links

Table of Contents

• Task 2: Paragraph and Links

  • Paragraphs and Text Block

    • RST Links

      • External Links

      • Internal Links

    • References

  • Task

  • Text to Add

Paragraphs and Text Block

Paragraphs are blocks of text with a blank line between then. Line breaks are ignored.

Blockquotes are intended paragraphs or other text blocks

Here is a block quote.

Here is the second paragraph of the block quote.

Paragraphs are blocks of test with a blank line between then.
Line breaks
are ignored.

Blockquotes are indented paragraphs or other text blocks

    Here is a block quote.

    Here is the second paragraph of the block quote.

Note

You will learn quickly that spaces and line breaks are very important in reStucturedText.

RST Links

External Links

RST provides several options for building links to external sites, two of which are Direct link or target definition. Sphinx automatically links raw URLs

Direct link (single use):

`Link text <link URL>`_

Get the latest news at `BBC <https://bbc.com/>`_.

Target definition (reuse):

Get the latest news at `BBC`_.  You can get more than just
news at `BBC`_, such as British culture and entrainment.

.. _BBC: https://bbc.com/

Internal Links

You can link to a specific heading by name if all heading text is unique. We’ve found this unlikely in a larger project.

A way to build links to headings is to use a custom anchor that goes above a heading directly.

This code block defines two targets that you can link to directly using the ::ref:`Label` command. By default, Sphinx displays the heading text in the link.

.. _RST Overview:

Overview
**********

RST Overview content


.. _Sphinx Overview:

Overview
*********

Sphinx Overview content

Build the links using the :ref:`Label` command.

Content editors should read the RST :ref:`RST Overview`
to learn about RST.

System admins should read the Sphinx :ref:`Sphinx Overview`
to learn how to configure the system.

For example, this page has a target defined as .. _Writing in RST - Task 2: that we can link to from any page in sphinx. Clicking Task 2: Paragraph and Links will take you to the top of this page.

References

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

• https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#internal-and-external-links

• https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst

---

Task

Task 2: Add the following text to the overview section to learn about using paragraphs, inline markup, and creating hyperlinks.

• Use inline styles

• Link the URL to text Install Sphinx guide

---

Text to Add

**Sphinx** is a platform that *renders RST files* to a web application
that is suitable for documentation. This guide provides a quick
installation guide for someone wanting to set up Sphinx on a VSP.

The install sphinx guide <https://www.sphinx-doc.org/en/master/usage/quickstart.html>
provides a good starting point, but we will make other changes to install
the latest version of Sphinx from PyPI.

The VPS setup for this workshop uses Docker image nginx\:latest
<https://hub.docker.com/_/nginx>, which uses Debian 10.