reStructuredText Basics.rst



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.

Project setup

Install Python


Most Windows users do not have Python installed by default, so we begin with the installation of Python itself.
To check if you already have Python installed, if not  open the command prompt (Win-r and type cmd).
Once the command prompt is open, type python --version and press Enter.
To install python use this link https://www.python.org/downloads/release/python-390/

If Python is installed, you will see the version of Python printed to the screen.


Install pip

Once Python is installed, check for pip which will be installed by default. Enter pip --version in command promt to check if the pip is installed in windows.
For python version later than 3.0, pip is already installed. Just make sure to upgrade pip using the command python -m pip install --upgrade pip.


Check for sphinx installed

once the pip is installed check for sphinx , open the command prompt (Win-r and type cmd) enter pip install sphinx.


Adding scripts to the the Envionment variable


Navigate to control panel>system and security>system

Click advanced system settings>advanced>environment variables
Select path and click edit

Click new and add c:/user/<username>/appdata/local/programs/python/python39/script

click ok


Create the files


Open command promt then type sphinx-quickstart

Select root path by entering y letter
enter project name, author name, project release name
Then select project language by entering y letter
command will appear like see the command that finished an intial directory structure has been created.
Now go to local file and check for source folder.
Inside source folder rst file will be there.


How to do authoring


Open rst file in note pad++
Type the content or edit it then save it.
Now to get the HTML format open command promt and enter make html
Go to build file in local folder
Search for html folder and then check for html file, open it in browser.
If you want make any chages in the content then edit rst file and save it.


How to use reStructuredText
Formatting the main text
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:

Use one asterisk (text) for italics
Use two asterisks (text) for bolding
Use two backticks (text) for code samples.

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/.

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
First section heading level (h2) use “*”
Second section heading level (h3) use “=”
Third section heading level (h4) use “-“


Lists
For creating list just place an asterisk(*) or hyphen (-) atat 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:

This is a bulleted list.
It has two items, the second
item uses two lines.


This is a numbered list.
It has two items too.
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.
For example, this unordered list:

A list of
short items
that should be
displayed
horizontally
so it doesn't
use up so much
space on
the page


Images
reST supports an image directive, used like so: .. image:: gnu.png
example


Directives
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.
First we need to give  colon (..) then write toctree and close it with colon again.
next step enter space 3 times then give colon and enter maxdepth close it wiht colon again.
last step is enter space 3 times again and write reference files

List Table
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.
Example

Frozen Delights!


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
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.
The data may be internal (an integral part of the document) or external (a separate file).
Example

Frozen Delights!


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!


Roles
Cross-referencing syntax
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
math
Since Pythagoras, we know that a^2 + b^2 = c^2
we know that, algebric formula
a^2 + b^2 + 2ab = (a+b)^2

Reference
https://www.sphinx-doc.org/en/master/usage/installation.html
https://www.sphinx-doc.org/en/master/contents.html