-
Pooja Halappanavar authoredPooja Halappanavar authored
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
- Installation
Open this link for complete installation process
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html
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 (-) 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:
- This is a bulleted list.
- It has two items too.
- 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: .. 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 (..) give one space then write toctree and close it with colon again.
Next step enter space three times then give colon and enter maxdepth close it with colon again.
last step is enter space three times and write reference files names.
example
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
| 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
| 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