btrfs-progs: docs: add sample RSTified manual page

The asciidoc format needs to be tweaked but otherwise is basically the
same. Changes:

- bold text is ** **
- italics is * *
- NOTE is directive .. note
- definition list is simple indented block after the term
- section NAME in the manual page is generated from date in
  conf.py:man_pages
- new page has to be added to the index

To do:

- references to other manual pages, will be RST native linking once all
  the pages are converted

The output is in Documentation/_build/man and the format is visually not
much different from what is generated by asciidoc.

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

Documentation/btrfs-select-super.rst

@@ -0,0 +1,46 @@
+btrfs-select-super(8)
+=====================
+
+SYNOPSIS
+--------
+
+**btrfs-select-super** -s number <device>
+
+DESCRIPTION
+-----------
+
+Destructively overwrite all copies of the superblock with a specified copy.
+This helps in certain cases, for example when write barriers were disabled
+during a power failure and not all superblocks were written, or if the primary
+superblock is damaged, eg. accidentally overwritten.
+
+The filesystem specified by *device* must not be mounted.
+
+.. note::
+   Prior to overwriting the primary superblock, please make sure that the
+   backup copies are valid!
+
+To dump a superblock use the **btrfs inspect-internal dump-super** command.
+
+Then run the check (in the non-repair mode) using the command **btrfs check -s**
+where *-s* specifies the superblock copy to use.
+
+Superblock copies exist in the following offsets on the device:
+
+- primary: 64KiB (65536)
+- 1st copy: 64MiB (67108864)
+- 2nd copy: 256GiB (274877906944)
+
+A superblock size is 4KiB (4096).
+
+OPTIONS
+-------
+
+-s|--super <N>
+        use Nth superblock copy, valid values are 0 1 or 2 if the
+        respective superblock offset is within the device size
+
+SEE ALSO
+--------
+
+btrfs(8)

Documentation/conf.py

@@ -16,7 +16,7 @@
 
 # -- Project information -----------------------------------------------------
 project = 'BTRFS'
-# TODO: date
+# TODO: get from date
 copyright = '2021'
 
 # TODO: copy from ../VERSION
@@ -38,3 +38,7 @@ html_theme = 'sphinx_rtd_theme'
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+man_pages = [
+    ('btrfs-select-super', 'btrfs-select-super', 'overwrite primary superblock with a backup copy', '', '8')
+]

Documentation/index.rst

@@ -1,20 +1,17 @@
-.. BTRFS documentation master file, created by
+.. BTRFS documentation master file
-   sphinx-quickstart on Tue Oct 26 22:26:45 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 Welcome to BTRFS documentation!
 ===============================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
+   man-index
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

Documentation/man-index.rst

@@ -0,0 +1,14 @@
+.. BTRFS manual pages index
+
+Manual pages
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   btrfs-select-super
+
+Indices
+=======
+
+* :ref:`genindex`