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 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.
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**
=================
1. **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.
.. figure:: /images/python.png
2. **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**.
once the pip is installed check for sphinx , open the command prompt (Win-r and type cmd) enter pip install sphinx.
.. figure:: /images/pipinstallsphinx.png
4. **Adding scripts to the the Envionment variable**
2. **Adding scripts to the the Envionment variable**
* Navigate to control panel>system and security>system
...
...
@@ -57,46 +32,46 @@ once the pip is installed check for sphinx , open the command prompt (Win-r and
* Click **new** and add **c:/user/<username>/appdata/local/programs/python/python39/script**
* click **ok**
* Click **ok**
.. figure:: /images/Environment variable.png
.. figure:: /images/path.png
5. **Create the files**
3. **Creating the files**
* Open command promt then type **sphinx-quickstart**
* Select root path by entering y letter
* enter project name, author name, project release name
* 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.
* 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.
* Now go to local file and check for source folder
* Inside source folder rst file will be there.
* Inside source folder rst file will be there
.. figure:: /images/quickstart.png
5. **How to do authoring**
4. **How to do authoring**
* Open rst file in note pad++
* Type the content or edit it then save it.
* 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.
* 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.
* If you want make any chages in the content then edit rst file and save it
.. figure:: /images/source.png
...
...
@@ -109,13 +84,13 @@ once the pip is installed check for sphinx , open the command prompt (Win-r and
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:
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.
* 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/>`_.
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**
===========
...
...
@@ -134,11 +109,10 @@ Headers are demarcated by non-alphanumeric characters like dashes, equal signs,
**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:
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, the second
item uses two lines.
* It has two items too.
3. This is a numbered list.
4. It has two items too.
...
...
@@ -150,8 +124,7 @@ For creating list just place an asterisk(*) or hyphen (-) atat the start of a pa
**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.
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:
...
...
@@ -169,7 +142,7 @@ For example, this unordered list:
**Images**
==========
reST supports an image directive, used like so: .. image:: gnu.png
reSt supports an image directive, used like: .. image:: gnu.png
*example*
...
...
@@ -178,13 +151,17 @@ reST supports an image directive, used like so: .. image:: gnu.png
**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.
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
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.
