2. Comparison with Markdown

2.1. Advantages

• The flexibility of complex lists with sub-lists is not even approached by Markdown.

• The flexibility of tables is not even approached by Markdown.

• Cross-references between files is supported. Sphinx adds capabilities to reST that make it even easier.

• Complex paragraphs are easy and intuitive and not well supported by Markdown.

2.2. Disadvantages

• The ability to nest bold, italic and underlined text is not built in. It can, however, be implemented via custom text roles.

  The workaround for this is fairly simple:

  custom.css:

  /*-------------------------------------------------------------------------
   * Custom Roles:  workarounds for reStructuredText parser shortcomings.
   * These use `custom_roles.txt` to set up roles using these class names.
   *
   * To use them in `.rst` files:
   * ----------------------------
   * 1.  .. include::  <doc_root>/include/custom_roles.txt
   * 2.  Use with custom roles like this:
   *         :bi:`text`
   *         :ib:`text`
   *         :u:`text`
   *         :ub:`text`
   *         :bu:`text`
   *         :ui:`text`
   *         :iu:`text`
   *         :ubi:`text`
   *         :uib:`text`
   *         :bui:`text`
   *         :iub:`text`
   *         :biu:`text`
   *         :ibu:`text`
   *
   * The above combinations were done so you don't have to remember
   * whether 'i', 'b' or 'u' comes first when they are combined.
   *-------------------------------------------------------------------------*/
  span.bi {
    font-weight: bold;
    font-style: italic;
  }
  span.ul {
    text-decoration: underline;
  }
  span.bu {
    text-decoration: underline;
    font-weight: bold;
  }
  span.iu {
    text-decoration: underline;
    font-style: italic;
  }
  span.ubi {
    text-decoration: underline;
    font-weight: bold;
    font-style: italic;
  }
  

  Then in a <doc_root>/include/custom_roles.txt file you include where needed using .. include:: /include/custom_roles.txt (or in every document if you wish to ensure these custom roles are always available):

  .. ========================================================================
  .. Workarounds for reStructuredText parser shortcomings.
  .. These use `custom.css` to set up styling using these class names.
  .. ========================================================================
  .. role:: bolditalic
      :class: bi
  .. role:: bi
      :class: bi
  .. role:: ib
      :class: bi
  .. role:: underlined
      :class: ul
  .. role:: u
      :class: ul
  .. role:: ul
      :class: ul
  .. role:: ub
      :class: bu
  .. role:: bu
      :class: bu
  .. role:: ui
      :class: iu
  .. role:: iu
      :class: iu
  .. role:: ubi
      :class: ubi
  .. role:: uib
      :class: ubi
  .. role:: bui
      :class: ubi
  .. role:: iub
      :class: ubi
  .. role:: biu
      :class: ubi
  .. role:: ibu
      :class: ubi