diff --git a/documentation/source/readme/reStructuredText Basics.rst b/documentation/source/readme/reStructuredText Basics.rst index 9950b71c470f8978579a2804059b2f9e8b205d8e..9641524111940a2eb7c50d119abd2cafc9f35acc 100644 --- a/documentation/source/readme/reStructuredText Basics.rst +++ b/documentation/source/readme/reStructuredText Basics.rst @@ -1,254 +1,35 @@ -Introduction to reStructuredText -################################ +Documentation using Sphinx +########################## -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. +This topic aims to describe a standard way of documenting using reStructuredText with Sphinx and publising to ReadTheDocs. reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document. -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. +Sphinx installation +******************* +Sphinx is written in Python and supports Python 3.6+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed. For more details on Sphinx Installation, see https://www.sphinx-doc.org/en/master/usage/installation.html. -Project setup -************* +Setting up the documentation sources +==================================== -Open this open for complete installation process. +The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation. -`<https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html>`_ +Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, enter the below command in windows prompt: -How to use reStructuredText -*************************** +.. code:: cpp -Paragraph -========= + sphinx-quickstart -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: +The below quickstart screen appears as shown below: -*Syntax* +.. figure:: images/quick-start.PNG -.. code-block:: console + :align: center + :alt: Quickstart overview - * Use one asterisk (*text*) for italic - * Use two asterisks (**text**) for bold - * Use two backticks (``text``) for code sample +**Figure 1 quickstart utility** -*Output* -* 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 - -- First section heading level (h2) use “*†- -- Second section heading level (h3) use “=†- -- Third section heading level (h4) use “-“ - -*Syntax* - -.. code-block:: console - - Heading one - ########### - - Heading two - *********** - - Heading three - ============= - - Heading four - ------------ - -*Output* - -Heading one -########### - -Heading two -*********** - -Heading three -============= - -Heading four ------------- - - -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:: console - -* This is a bulleted list. -* It has two items, the second - item uses two lines. - -1. This is a numbered list. -2. It has two items too. - -#. This is a numbered list. -#. It has two items too. - -*Output* - -* This is a bulleted list. -* It has two items, the second - item uses two lines. - -1. This is a numbered list. -2. It has two items too. - -#. This is a numbered list. -#. It has two items too. - - -Images -====== - -reST supports an image directive: - -*Syntax* - -.. code-block:: console - -.. figure:: Images/multi_data.png - -*Output* - -.. 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: - -Simple table ------------- - -*Syntax* - -.. code-block:: console - -===== ===== ======= -A B A and B -===== ===== ======= -False False False -True False False -False True False -True True True -===== ===== ======= - -*Output* - -===== ===== ======= -A B A and B -===== ===== ======= -False False False -True False False -False True False -True True True -===== ===== ======= - -Grid tabble ------------ - -*Syntax* - -.. code-block:: console - -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | ... | ... | | -+------------------------+------------+----------+----------+ - -*Output* - -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | ... | ... | | -+------------------------+------------+----------+----------+ - -Two more syntaxes are supported: CSV tables and List tables `<https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table>`_. - -Hyperlinks -========== - -External --------- - -If the link is provided for any website then use this syntax: - -*Syntax* - -.. code-block:: console - -`<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks>`_ - -*Output* - -`<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks>`_ - -Internal --------- -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>`_. - - -Roles -===== - -Math ----- - -*Syntax* - -.. code-block:: console - -Since Pythagoras, we know that :math:`a^2 + b^2 = c^2` - -we know that, algebric formula - -:math:`a^2 + b^2 + 2ab = (a+b)^2` - - - -*Output* - -Since Pythagoras, we know that :math:`a^2 + b^2 = c^2` - -we know that, algebric formula - -:math:`a^2 + b^2 + 2ab = (a+b)^2` - - -Reference -========= - -`<https://www.sphinx-doc.org/en/master/contents.html>`_ - -`<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ - -`<https://docs.zephyrproject.org/latest/guides/documentation/index.html>`_ \ No newline at end of file +Defining Document Structure +===========================