btrfs-progs: docs: convert conventions to RST

Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/DocConventions.rst

@@ -1,52 +1,51 @@
-Convention and style used for manual pages
-------------------------------------------
+Conventions and style for documentation
+---------------------------------------
 
 Manual pages structure:
 
 - add references to all external commands mentioned anywhere in the text to the
-  'SEE ALSO' section
+  *SEE ALSO* section
   - also add related, not explicitly mentioned
 - the heading levels are validated
   - mandatory, manual page ===
   - mandatory, sections ---
-  - optional, sub-sections ~~~
+  - optional, sub-sections ^^^
 - command-specific examples are mostly free of restrictions but should be
   readable in all output formats (manual page, html)
 
 - subcommands are in alphabetical order
 
 - long command output or shell examples: verbatim output
-  - a new paragraph, 2 spaces at the beginning of the line, or the comment block
+  - use code-block:: directive
 
 Quotation in subcommands:
 
-- exact syntax: monotype `usage=0`
-- reference to arguments etc: 'italics'
-- command reference: bold *btrfs filesystem show*
-  - subcommand names should be spelled in full, ie. 'filesystem' instead of 'fi'
-- section references: italics 'EXAMPLES'
+- exact syntax: monotype ``usage=0``
+- reference to arguments etc: *italics*
+- command reference: bold ``btrfs filesystem show``
+  - subcommand names should be spelled in full, ie. *filesystem* instead of *fi*
+- section references: italics *EXAMPLES*
 
 - argument name in option description: caps in angle brackets <NAME>
   - reference in help text: caps NAME
-    also possible: caps italics 'NAME'
+    also possible: caps italics *NAME*
 
 - command short description:
-  - command name: bold *command*
+  - command name: bold **command**
   - optional unspecified: brackets [options]
   - mandatory argument: angle brackets <path>
   - optional parameter with argument: [-p <path>]
 
 Other:
 
-- NOTE: at the beginning of the line, is rendered as a separate paragraph and
+- for notes use note:: directive, is rendered as a separate paragraph and
   should be used only for important information
 
-- WARNING: at the beginning of the line, is rendered as a separate paragraph
+- warning:: directive is rendered as a separate paragraph
   and most likely more visible than NOTE, use for critical information that
   may cause harm, irreversible state or performance problems
   - should point reader to other part of documentation to seek more details
 
-
 References:
-- full asciidoc syntax: http://asciidoc.org/userguide.html
-- cheatsheet: http://powerman.name/doc/asciidoc
+- RST and Sphinx Cheatsheet https://spl.hevs.io/spl-docs/writing/rst/cheatsheet.html
+- RST Cheat Sheet https://sphinx-tutorial.readthedocs.io/cheatsheet/