Update rst cheat sheet

intro/contribution/rst-cheat-sheet.rst

@@ -3,7 +3,33 @@
 ReStructuredText Cheat Sheet
 ############################
 
-BeagleBoard docs is mostly written with ReStructuredText (r)
+BeagleBoard.org docs site uses ReStructuredText (rst) which is a file format [#]_ for textual data used primarily 
+in the Python programming language community for technical documentation. It is part of the Docutils 
+project of the Python Doc-SIG, aimed at creating a set of tools for Python similar to Javadoc for Java 
+or Plain Old Documentation for Perl. If you are new with rst you may go through this rst cheat sheet [#]_ [#]_ [#]_
+chapter to gain enough skills to edit and update any page on the BeagleBoard.org docs site. some things 
+you should keep in mind while working with rst,
+
+
+1. like Python, RST syntax is sensitive to indentation !
+2. RST requires blank lines between paragraphs
+
+Text formatting
+****************
+
+With asterisk you can fomat the text as italic & bold,
+
+1. Sinlge asterisk (``*``) like ``*emphasis*`` gives you *italic text*
+2. Double asterisk (``**``) like ``**strong emphasis**`` gives you **blod text**
+
+With backquote character (`) you can format the text as link & inline literal.
+
+1. See `Links`_ section on how single backquote can be used to create a link linke `this <www.beagleboard.org>`_.
+2. With double back quotes before and after text you can easily create ``inline lierals``.
+
+.. note::
+    backquote can be found below escape key on most keyboards.
+
 
 Headings
 *********
@@ -40,4 +66,184 @@ more) the at least of the heading text, for example:
 
         <2> Shows the correct way of setting the document title (H1) with ``#``.
 
+
+Code
+*****
+
+For adding a code snippet you can use tab indentation to start. For more refined code snippet display
+we have the ``code-block`` and ``literalinclude`` directives as shown below.
+
+
+Indentation
+============
+
+This the simplest way of adding code snippet in ReStructuredText.
+
+.. callout::
+
+    .. code-block:: ReStructuredText
+
+        This is python code:: <1>
+            <2>
+            import numpy as np <3>
+            import math
     
+    .. annotations::
+
+        <1> Provide title of your code snippet and add ``::`` after the text.
+
+        <2> Empty line after the title is required for this to work.
+
+        <3> Start adding your code.
+
+
+Output
+------
+
+This is python code::
+
+    import numpy as np 
+    import math
+
+Code block
+===========
+
+Simple indentation only supports python program highlighting but, with code block you can 
+specify which language is your code written in. ``code-block`` also provides better readability 
+and line numbers support you can useas shown below.
+
+.. callout::
+
+    .. code-block:: ReStructuredText
+
+        .. code-block:: python <1>
+            :linenos: <2>
+
+            import numpy as np <3>
+            import math
+
+
+    .. annotations::
+
+        <1> Start with adding ``.. code-block::`` and then add language of code like python, bash, javascript, etc.
+        
+        <2> Optionally, you can enable line numbers for your code.
+
+        <3> Start adding your code.
+
+Output
+------
+
+.. code-block:: python
+    :linenos: 
+
+    import numpy as np
+    import math
+
+
+Literal include
+================
+
+To include the entire code or a code snippet from a program file you can use this directive.
+
+.. callout::
+
+    .. code-block:: ReStructuredText
+
+        .. literalinclude:: filename.cpp <1>
+            :caption: <2>
+            :linenos: <3>
+            :language: C++ <4>
+            :lines: 2, 4-7 <5>
+            :start-after: 4 <6>
+            :end-before: 7 <7>
+            :lineno-start: 113 <8>
+
+    .. annotations::
+
+        <1> Provide the code file destination.
+
+        <2> Provide caption for the code.
+        
+        <3> Enable line numbers.
+
+        <4> Set programming language.
+
+        <5> Cherry pick some lines from a big program file.
+
+        <6> Display the code snippet from a specific line number.
+
+        <7> Set a specific line number as end of code snippet.
+
+        <8> Instead of starting line number from 1 start it with some other number. It's useful when you use :lines:, :start-after:, and :end-before:.
+
+Links
+******
+
+We have three types of links to use in sphinx,
+
+1. External links (http(s) links).
+2. Implicit links to title (within same rst file).
+3. Explicit links (labels that can be used anywhere in the project).
+
+External links
+***************
+
+For a simple link to a site the format is
+
+.. code-block:: rst
+
+    `<www.beagleboard.org>`_
+
+this will be rendered as `<www.beagleboard.org>`_. 
+
+You can also include a label to the link as shown below.
+
+.. code-block:: rst
+
+    `BeagleBoard.org <www.beagleboard.org>`_
+
+this will be rendered as `BeagleBoard.org <www.beagleboard.org>`_. 
+
+Implicit Links
+***************
+
+These are basically the headings inside the rst page which can 
+be used as a link to that section within document. 
+
+.. code-block:: rst
+
+    `Links`_
+
+when rendered it becomes `Links`_
+
+Explicit link
+*************
+
+These are special links you can assign to a specific part of the document and reference anywhere 
+in the project unlike implicit links which can be used only within the document they are defined. 
+On top of each page you'll see some text like ``.. _rst-cheat-sheet:`` is used to create a
+label for this chapter. These are called the explicit links amd you can reference these using two methods.
+
+.. code-block:: rst
+    :linenos:
+
+    rst-cheat-sheet_
+
+.. code-block:: rst
+    :linenos:
+    :lineno-start: 2
+
+    :ref:`<rst-cheat-sheet>`_
+
+Both can be used inside/outside of the document and the rendered link will take you directly to that specific segment.
+
+.. rubric:: footnotes
+
+.. [#] `reStructuredText wiki page <https://en.wikipedia.org/wiki/ReStructuredText>`_
+
+.. [#] `Sphinx and RST syntax guide (0.9.3) <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#internal-and-external-links>`_
+
+.. [#] `Quick reStructuredText (sourceforge) <https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets>`_
+
+.. [#] `A two-page cheatsheet for restructured text <https://github.com/ralsina/rst-cheatsheet>`_
\ No newline at end of file