documentation/sphinx: Fix formatting errors in .rst files

Fixes broken references to other documents/sections.
Adds `Host Identity` to the API reference.

docs/README.rst

@@ -1,5 +1,5 @@
 NimBLE Bluetooth Stack Documentation
-#################################
+####################################
 
 This folder holds the documentation for the NimBLE Bluetooth stack from the
 `Apache Mynewt`_ project. It is  built using `Sphinx`_.
@@ -19,8 +19,8 @@ Previewing Changes
 ==========================
 
 In order to preview any changes you make you must first install a Sphinx
-toolchain as described at https://github.com/apache/mynewt-documentation#id3.
+toolchain as described at https://github.com/apache/mynewt-documentation.
- Then:
+Then:
 
 .. code-block:: bash
 

docs/ble_hs/ble_hs_id.rst

@@ -43,3 +43,10 @@ Header
 .. code-block:: cpp
 
     #include "host/ble_hs.h"
+
+API
+~~~
+
+.. doxygengroup:: bt_host_id
+   :content-only:
+   :members:

docs/ble_setup/ble_addr.rst

@@ -52,12 +52,12 @@ Method 3: Configure a random address at runtime
 Random addresses get configured through the NimBLE host. The following
 two functions are used in random address configuration:
 
--  :doc:`ble_hs_id_gen_rnd <../ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd>`:
+-  :c:func:`ble_hs_id_gen_rnd`:
    Generates a new random address.
--  :doc:`ble_hs_id_set_rnd <../ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd>`:
+-  :c:func:`ble_hs_id_set_rnd`:
    Sets the device's random address.
 
-For an example of how this is done, see the :doc:`<../../../os/tutorials/ibeacon>`.
+For an example of how this is done, see the :doc:`../../../tutorials/ble/ibeacon`.
 
 *Note:* A NimBLE device can be configured with multiple addresses; at
 most one of each address type.

docs/btshell/btshell_GAP.rst

@@ -411,7 +411,7 @@ Advertising with Extended Advertising enabled
 +------------------------------+--------------------------+----------------------------+-------------------------------------------------------------------------------------+
 |                              | scan\_req\_notif         | [``0``-1]                  | Enable SCAN\_REQ notifications                                                      |
 +------------------------------+--------------------------+----------------------------+-------------------------------------------------------------------------------------+
-| **advertise-set-addr**       |                          |                            | Configure *random* address for instance                                              |
+| **advertise-set-addr**       |                          |                            | Configure *random* address for instance                                             |
 +------------------------------+--------------------------+----------------------------+-------------------------------------------------------------------------------------+
 |                              | instance                 | [``0``-UINT8\_MAX]         | Advertising instance                                                                |
 +------------------------------+--------------------------+----------------------------+-------------------------------------------------------------------------------------+