Merge branch 'for-url-work' into development-merge

# Conflicts:
#	docs/api/usb/USBAudio.md
#	docs/contributing/guidelines/workflow.md

Author: AnotherButler

docs.json

@@ -1,5 +1,6 @@
 {
     "product_name": "Mbed OS 6",
+    "split_pages_on": "h1",
     "books": [{
             "title": "Mbed OS API doxygen",
             "description": "The full Mbed OS API documentation in doxygen format",
@@ -173,7 +174,7 @@
             ]
         },
         {
-            "title": "APIs",
+            "title": "Full API references",
             "description": "The APIs of Mbed OS: RTOS, I/O, storage, networking, Cloud connection, security, power, memory and utilities",
             "slug": "apis",
             "type": "markdown",
@@ -664,13 +665,10 @@
                 },
                 {
                     "title": "Bluetooth",
-                    "sub_chapters": [{
-                            "title": "Concepts",
-                            "intro": {
-                                "path": "docs/api/bluetooth/bluetooth.md"
-                            },
-                            "sources": []
-                        },
+                    "intro": {
+                        "path": "docs/api/bluetooth/bluetooth.md"
+                    },
+                    "sub_chapters": [
                         {
                             "title": "Options and config",
                             "intro": {

docs/api/bluetooth/BatteryService.md

@@ -1,19 +1,19 @@
-## BatteryService
+# BatteryService
 
 It is often a requirement for devices operating on battery to report the battery charge level to the user.
 
 The [Bluetooth Battery Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245138) defines how to expose a battery charge level through a BLE link. It allows a client - usually a smartphone application - of a device to read the current battery charge level and follow its evolution.
 
 The BatteryService class implements the Bluetooth Battery Service as defined by the Bluetooth SIG. Makers of BLE devices operating on battery can use the API to expose interoperably the charge level of their products.
 
-### BatteryService class reference
+## BatteryService class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/class_battery_service.html)
 
-### BatteryService example
+## BatteryService example
 
 [![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-ble/blob/master/BLE_BatteryLevel/source)](https://github.com/ARMmbed/mbed-os-example-ble/blob/mbed-os-5.14/BLE_BatteryLevel/source/main.cpp)
 
-### Related content
+## Related content
 
 - [Bluetooth Battery Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245138) specification.

docs/api/bluetooth/EnvironmentalService.md

@@ -1,11 +1,11 @@
-## EnvironmentalService
+# EnvironmentalService
 
 [Add description here.]
 
-### EnvironmentalService class reference
+## EnvironmentalService class reference
 
 [![View code](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_environmental_service.html)
 
-### EnvironmentalService example
+## EnvironmentalService example
 
 [Add example here.]

docs/api/bluetooth/Gap.md

@@ -1,4 +1,4 @@
-## GAP
+# GAP
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
@@ -12,19 +12,19 @@ The other side of the process is the act of scanning, which listens for advertis
 
 Advertising, scanning and connection all have parameters that let you find a compromise between desired power consumption levels, latency and efficiency of these processes.
 
-### Advertising
+## Advertising
 
 Advertising consists of broadcasting at a regular interval a small amount of data containing valuable information about the device. Peer devices listening on BLE advertising channels may scan these packets.
 
 Scanners may also request additional information from device advertising by sending a scan request. If the broadcaster accepts scan requests, it can reply with a scan response packet containing additional information.
 
-### Scanning
+## Scanning
 
 Scanning consists of listening for peer advertising packets. From a scan, a device can identify devices available in its environment.
 
 If the device scans actively, it sends scan request to scannable advertisers and collects their scan responses.
 
-### Extended and periodic advertising
+## Extended and periodic advertising
 
 BLE controllers supporting Bluetooth 5.0 may offer additional advertising and scanning options. Use `isFeatureSupported()` to check feature availability.
 
@@ -36,13 +36,13 @@ There may be many advertising sets active at one time on a single advertiser. Th
 
 Devices that do not support extended and periodic advertising will not see these advertisements. You may use legacy advertising alongside extended advertising, running at the same time, to support older devices in the environment.
 
-### Privacy
+## Privacy
 
 Privacy is a feature that allows a device to avoid being tracked by other (untrusted) devices. The device achieves it by periodically generating a new random address. The random address may be a resolvable random address, enabling trusted devices to recognize it as belonging to the same device. These trusted devices receive an Identity Resolution Key (IRK) during pairing. The SecurityManager handles this and relies on the other device accepting and storing the IRK.
 
 You need to enable privacy by calling `enablePrivacy()` after initializing the SecurityManager because privacy requires SecurityManager to handle IRKs. Set the behavior of privacy enabled devices by using `setCentralPrivacyConfiguration()`, which specifies what the device should be with devices using random addresses, and `setPeripheralPrivacyConfiguration`. Random addresses that privacy enabled devices generate can be of two types: resolvable (by devices who have the IRK) and unresolvable. You can't use unresolvable addresses for connecting and connectable advertising; therefore, use a resolvable one for these, regardless of the privacy configuration.
 
-### Modulation schemes
+## Modulation schemes
 
 When supported by the host and controller, you can select different modulation schemes:
 
@@ -56,7 +56,7 @@ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`
 
 You may query the currently used PHY using `readPhy()`, which returns the result through a call to the registered event handler. You may register the handler with `setEventHandler()`. The events inform about the currently used PHY and of any changes to PHYs, which the controller or the peer may trigger autonomously.
 
-### Data length (over-the-air MTU)
+## Data length (over-the-air MTU)
 
 In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.
 
@@ -66,11 +66,11 @@ The default value of data length supported by all controllers is 23 octets. If b
 
 `ATT_MTU` and data length are independent of each other.
 
-### GAP class reference
+## GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)
 
-### GAP example
+## GAP example
 
 Here is an example demonstrating how to use the GAP API to advertise, scan, connect and disconnect and how parameters influence efficiency of these actions.
 

docs/api/bluetooth/GattClient.md

@@ -1,24 +1,24 @@
-## GattClient
+# GattClient
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
 You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
 
-### Discovery procedures
+## Discovery procedures
 
 A GattServer hosts a fixed set of services. These services are a logical composition of characteristics that may be discovered, read or written and can broadcast their state to a connected client. These characteristics may also contain metainformation and named characteristic descriptors. A characteristic descriptor may indicate the unit used for a characteristic value, describe the characteristic purpose in a textual form or allow a client to register for update notifications for the characteristic value.
 
 Prior to any interaction with a server characteristic, a GattClient discovers the layout of the services and characteristics present on the server.
 
 The layout of the descriptors of a characteristic may also be issued as an extra discovery step.
 
-### Attribute manipulation
+## Attribute manipulation
 
 As a result of the discovery process, the client can start interacting with the characteristic discovered. Depending on the characteristic properties (acquired during discovery), a client can read or write the value of a given characteristic.
 
 Mbed BLE abstracts read and write operations to offer a single API that can be used to read or write characteristic values. The application code does not have to handle the necessary fragmentation or reassembly process if the attribute value to be transported can't fit in a single data packet.
 
-### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+## Attribute Protocol Maximum Transmission Unit (ATT_MTU)
 
 `ATT_MTU` is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet are split across multiple operations.
 
@@ -28,16 +28,16 @@ Only `GattClient` can trigger the exchange of `ATT_MTU` between client and serve
 
 `ATT_MTU` is at least 23 octets by default. If a larger size is negotiated, the user application will be informed through the `onAttMtuChange` function called in the `GattClient::EventHandler`. (`GattServer::EventHandler` is also informed.)
 
-### Server initiated events
+## Server initiated events
 
 When a server updates a characteristic value, it can forward the new value to any registered clients. Clients may register for these updates on a per-characteristic basis. The server sends the updates by using notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimizes the number of transactions between a client and a server by avoiding polling.
 
 Clients register for these updates by setting the Client Characteristic Configuration Descriptor (CCCD) value. This is an attribute, and the client needs to discover its descriptor. It is present in the characteristic if its notify or indicate properties are set.
 
-### GattClient class reference
+## GattClient class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_client.html)
 
-### GattClient example
+## GattClient example
 
 [![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattClient/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattClient/file/38639a71a0f1/source/main.cpp)

docs/api/bluetooth/GattServer.md

@@ -1,28 +1,28 @@
-## GattServer
+# GattServer
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
 You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction.
 
 `GattServer` is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
 
-### Server layout
+## Server layout
 
 Application code can add a GattService object to the server with the help of the function `addService()`. That function registers all the GattCharacteristics enclosed in the service, as well as all the characteristic descriptors (see GattAttribute) that these characteristics contain. Service registration assigns a unique handle to the various attributes that are part of the service. The user must use this handle to read or write these components.
 
 There are no defined primitives that remove a single service; however, a call to the function `reset()` removes all services previously registered in the GattServer.
 
-### Characteristic and attributes access
+## Characteristic and attributes access
 
 You must access values of the characteristic and the characteristic descriptor present in the GattServer through the handle assigned to them when you registered the service. The GattServer class offers several types of `read()` and `write()` functions that retrieve or mutate an attribute value.
 
 You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.
 
-### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+## Attribute Protocol Maximum Transmission Unit (ATT_MTU)
 
 The Attribute Protocol Maximum Transmission Unit (`ATT_MTU`) is the maximum size of the attribute protocol packet. For details, please see the [GattClient Documentation](../apis/gattclient.html).
 
-### Events
+## Events
 
 You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities:
 
@@ -35,10 +35,10 @@ You can register several event handlers with the GattServer that it will call to
 
 The term characteristic value update represents Characteristic Value Notification and Characteristic Value Indication when the nature of the server initiated is not relevant.
 
-### GattServer class reference
+## GattServer class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_server.html)
 
-### GattServer example
+## GattServer example
 
 [![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/file/622c672f6d5f/source/main.cpp)

docs/api/bluetooth/HeartRateService.md

@@ -1,4 +1,4 @@
-## HeartRateService
+# HeartRateService
 
 People practicing physical activities use heart rate monitors to track their pulse in real time and improve their physical performances.
 
@@ -8,15 +8,15 @@ The HeartRateService class implements the Bluetooth Heart Rate service as define
 
 <span class="note"> **Note:** The Bluetooth Heart Rate Service is part of the [Bluetooth Heart Rate Profile](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239865), which defines behaviors that a Bluetooth heart rate sensor expects. You must ensure that your application conforms to the heart rate profile to guarantee interoperability of your heart rate sensors.</span>
 
-### HeartRateService class reference
+## HeartRateService class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/class_heart_rate_service.html)
 
-### HeartRateService example
+## HeartRateService example
 
 [![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-ble/blob/master/BLE_HeartRate/source)](https://github.com/ARMmbed/mbed-os-example-ble/blob/mbed-os-5.14/BLE_HeartRate/source/main.cpp)
 
-### Related content
+## Related content
 
 - [Bluetooth Heart Rate Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239866) specification.
 - [Bluetooth Heart Rate Profile](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239865) specification.