From 4de0e5769c670ea9faa66c024342a00326188877 Mon Sep 17 00:00:00 2001
From: Deepak Khatri <lorforlinux@beagleboard.org>
Date: Thu, 3 Nov 2022 01:45:50 +0530
Subject: [PATCH] Update rst cheat sheet
---
intro/contribution/rst-cheat-sheet.rst | 208 ++++++++++++++++++++++++-
1 file changed, 207 insertions(+), 1 deletion(-)
diff --git a/intro/contribution/rst-cheat-sheet.rst b/intro/contribution/rst-cheat-sheet.rst
index 1adb70a9..4f472270 100644
--- a/intro/contribution/rst-cheat-sheet.rst
+++ b/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
--
GitLab