.. reStructuredText syntax summary .. Author: Benjamin Vandendriessche .. STATUS: production .. _reST_tutorial: ######################### reStructuredText Tutorial ######################### `reStructuredText `_ (reST) is a markup language, similar to Markdown but with a more elaborate syntax. We use the version as implemented in `Sphinx `_, which adds the ability to generate complex multi-page document structures. .. rubric:: Quick Navigation .. contents:: :local: :depth: 2 ---- *************** Getting Started *************** * Follow the :ref:`instructions ` to configure Sphinx on your system * Use a text editor with reST syntax, linting, and spell checking (US English) * Use ``.rst`` as the file extension * Use the provided :doc:`template ` * Write concisely and use a consistent section structure if possible .. hint:: The source of every document can be opened directly from the HTML page (``view page source``). ---- ****** Syntax ****** A quick primer tutorial can be found `here `__, and full reference documentation `here `__. Basic and Byteflies-specific syntax is summarized below. Sections ======== Sections are limited to 5 levels, one of which is the main title (level 1), of which there can be only one per document. The following convention is used: :: #################### Level 1 (Main Title) #################### *************** Level 2 Heading *************** Level 3 heading =============== Level 4 heading --------------- Level 5 heading ~~~~~~~~~~~~~~~ Note the difference in capitalization. Add a horizontal line before every level 2 heading by including four or more dashes (``----``) surrounded by blank lines. If you need to add a heading that does not belong in the main file structure, use the ``.. rubric:: Title`` directive. A paragraph is a block of text with the same indentation, separated by one blank line. By Python convention, use 4 spaces per indentation level. A literal block of text is preceded by ``::``, followed by a blank line. The draw the attention of the reader, the following emphasis text blocks can be used: :: .. hint:: .. attention:: .. warning:: .. danger:: .. note:: ``note`` should only be used before the main title (level 1), e.g. to inform people about the status of the document. All the others can be used in the text where appropriate. They are listed here in increasing order of severity, i.e. ``warning`` and ``danger`` should only be used when absolutely necessary lest *the boy who cried wolf* will appear. Inline markup ============= :: *italics* **bold** ``literal`` \escape :color:`string` (requires color definition at start of file) :sup:`string` (superscript) :sub:`string` (subscript) Lists ===== Limit numbered lists to 2 levels: :: 1. Level 1 item a) Level 2 item, indented by 4 spaces 2. Level 1 item .. hint:: ``#`` can be used to auto-number the items. Limit unordered lists to 3 levels: :: * Level 1 item - Level 2 item (indented by 4 spaces) - Level 3 item (indented by 4 spaces) .. warning:: Level 2 and higher list items should be separated by blank lines from the other levels or they will be rendered as key-value pairs (see below). Various other lists for term definitions are available. To generate a simple two column table: :: key value (indented by 4 spaces) key value (separated by at least 2 spaces) Syntax highlighting =================== :: .. code-block:: language :linenothreshold: 5 (number code lines if > 5) :emphasizelines: 3 (highlight line 3) code Tables ====== Complex tables can be generated, see e.g. `here `__ for an example. A simple table: :: ======== ======= ======== Header 1 Header2 Header 3 ======== ======= ======== Val 1 Val 2 Val 3 ======== ======= ======== Renders like this: ======== ======= ======== Header 1 Header2 Header 3 ======== ======= ======== Val 1 Val 2 Val 3 ======== ======= ======== .. hint:: Use this `table generator `_ to easily generate the syntax for more complex tables. References ========== Various ways of linking both within and between documents are available: 1. To add a URL: ```string `_`` 2. To refer to a heading within the same document: ```Heading`_`` 3. To link to another .rst file: ``:doc:`string ``` 4. To link to a specific section in the same or another ``.rst`` file: ``:ref:`string ```, where anchor is defined in the file as ``.. _anchor:`` 5. To print the content of another file (e.g. a snippet): ``.. include:: /path/file.rst`` (note the file extension) 6. To add a footnote: ``\ [1]_`` inline, which points to ``.. [1] String`` to generate the accompanying footnote (the ``\`` escape character is used to remove the space)\ [#]_ 7. To link to a file: ``:download:`string ``` .. hint:: If the "string" portion of a link is repeated in the same document, Sphinx will generate warnings. To suppress these warnings, use a ``__`` (double underscore). .. [#] Instead of explicitly numbering a footnote, use ``#`` to let Sphinx handle auto-increments. Images ====== Many options are available for the image and figure directives (see `here `__). A basic example for each is included below: :: .. image:: path/file.png :height: 100 px :width: 200 px :scale: 50 % :alt: alternate text (use to specify source if applicable) :align: left :: .. figure:: path/file.png :scale: 50 % :alt: alternate text Caption: one blank line followed by paragraph or ".." to bypass Legend: another blank line followed by paragraph