reStructuredText is an easy to read, what-you-see-is-what-you-get plainttext markup syntax and parser system. In other words reStructuredText is a lightweight markup language that is used in static site generators like Sphinx.
It contains robust tools for semantic markup, reusing content, and content filters for different kinds of outputs. It’s also easily extendible using custom directives that you can create yourself, allowing you to satisfy a wide variety of documentation needs.
Introduction to reStructuredText
********************************
What is reStructuredText?
-------------------------
reStructuredText is an easy to read, what-you-see-is-what-you-get plainttext markup syntax and parser system. In other words reStructuredText is a lightweight markup language that is used in static
site generators like Sphinx. It contains robust tools for semantic markup, reusing content, and content filters for different kinds of outputs.
It’s also easily extendible using custom directives that you can create yourself, allowing you to satisfy a wide variety of documentation needs.
reStructuredText is useful for creating simple web pages, and for standalone documents.
Why use reStructuredText?
=============================
-------------------------
reStructuredText is a lightweight markup language, so it’s easier to read in plain-text format compared to heavier markup languages like DITA and other XML-based formats.
You can easily find text editors that render reStructuredText with syntax highlighting and live previews, without having to invest in complex tools. Compared to some other lightweight markup languages like markdown, reStructuredText contains stronger semantic markup tools.
Some writers also prefer reStructuredText because the markup standards are more well-defined compared to markdown.
You can easily find text editors that render reStructuredText with syntax highlighting and live previews, without having to invest in complex tools. Compared to some other lightweight markup languages
like MarkDown, reStructuredText contains stronger semantic markup tools. Some writers also prefer reStructuredText because the markup standards are more well-defined compared to MarkDown.
Project setup
=================
-------------
For complete setup of Sphinx and its installation process, refer `<https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html>`_.
Paragraphs in reStructuredText are blocks of text separated by at least one blank line. All lines in the paragraph must be indented by the same amount.
Paragraphs in reStructuredText are blocks of text separated by at least one blank line. All lines in the paragraph must be indented by the same amount:
Inline markup for font styles is similar to markdown:
*Syntax*
**Syntax**
.. code-block::
```
* Use one asterisk (*text*) for italic
* Use two asterisks (**text**) for bold
* Use two backticks (``text``) for code sample
```
**Output**
* Use one asterisk (*text*) for italics
* Use two asterisks (**text**) for bolding
* Use two backticks (``text``) for code samples
*Output*
Links to external sites contain the link text and a bracketed URL in backticks, followed by an underscore: Link to write the docs `<https://www.writethedocs.org/>`_.
* Use one asterisk (*text*) for italic
* Use two asterisks (**text**) for bold
* Use two backticks (``text``) for code sample
Headers
===========
#######
Headers are demarcated by non-alphanumeric characters like dashes, equal signs, or tildes. Use the same character for headers at the same level. The following creates a header:
- Document title (h1) use “#” for the underline character
- Document title (h1) use “#” for the underline character
- First section heading level (h2) use “*”
- First section heading level (h2) use “*”
- Second section heading level (h3) use “=”
- Second section heading level (h3) use “=”
- Third section heading level (h4) use “-“
- Third section heading level (h4) use “-“
**Syntax**
*Syntax*
Heading1
#######
.. code-block::
Heading2
********
Heading one
===========
Heading3
========
Heading two
-----------
Heading4
--------
Heading three
#############
**Output**
Heading four
************
**Lists**
=========
*Output*
For creating list just place an asterisk(*) or hyphen (-) at the start of a paragraph and indent continuation lines with one space. The same goes for numbered lists; they can also be autonumbered using a (#) sign:
Heading one
===========
Heading two
-----------
*example*
Heading three
#############
**Syntax**
Heading four
************
.. figure:: Images/List.PNG
**Output**
List
####
For creating list just place an asterisk(*) or hyphen (-) at the start of a paragraph and indent continuation lines with one space. The same goes for numbered lists; they can also be autonumbered using a (#) sign:
*Syntax*
.. code-block::
* This is a bulleted list.
* It has two items too.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
...
...
@@ -99,133 +106,138 @@ For creating list just place an asterisk(*) or hyphen (-) at the start of a para
#. This is a numbered list.
#. It has two items too.
Multi-column lists
======================
If you have a long bullet list of items, where each item is short, you can indicate the list items should be rendered in multiple columns with a special .. rst-class:: rst-columns directive. The directive will apply to the next non-comment element (e.g., paragraph), or to content indented under the directive.
*Output*
*example*
* This is a bulleted list.
* It has two items, the second
item uses two lines.
**Syntax**
1. This is a numbered list.
2. It has two items too.
.. figure:: Images/multi-column_list.PNG
#. This is a numbered list.
#. It has two items too.
**Output**
Images
######
this unordered list:
reST supports an image directive:
.. rst-class:: rst-columns
*Syntax*
* A list of
* Displayed
* Horizontally
* Short items
* So it doesn't
* Space on
* That should be
* The page
* Use up so much
.. code-block::
.. figure:: /images/multi data.png
Images
==========
*Output*
reSt supports an image directive, used like: .. figure:: Images/image name.PNG
.. figure:: /images/multi data.png
*example*
.. figure:: Images/multi_data.PNG
Tables
######
The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items:
Directives
==============
Simple table
************
Directive is a generic block of explicit markup. While docutils provides a number of directives, sphinx provides many more and uses directives as one of the primary extension mechanism.
*Syntax*
*example*
.. code-block::
**Syntax**
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
.. figure:: Images/toctree.PNG
:width: 50px
:Height: 50px
*Output*
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
**Output**
Grid tabble
***********
List Table
==============
*Syntax*
The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items.
Two more syntaxes are supported: CSV tables and List tables `<https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table>`_.
Hyperlinks
----------
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
External
********
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
CSV table
=============
If the link is provided for any website then use this syntax:
The "CSV-table" directive is used to create a table from CSV (comma-separated values) data. CSV is a common data format generated by spreadsheet applications and commercial databases.
*Syntax*
The data may be internal (an integral part of the document) or external (a separate file).
Internal linking is done via a special reST role provided by Sphinx, Cross-referencing syntax `<https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_.
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
Roles
=========
-----
Math
****
*Syntax*
**Cross-referencing syntax**
.. code-block::gbv
Basically, you only need to write :role:`target` and a link will be created to the item named target of the type indicated by role.
Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`
we know that, algebric formula
**Math**
:math:`a^2 + b^2 + 2ab = (a+b)^2`
**Syntax**
.. figure:: Images/math.PNG
**Output**
*Output*
Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`
...
...
@@ -233,12 +245,12 @@ we know that, algebric formula
