Similar to commit fe99b819487d ("docs: i2c: i2c-sysfs: fix hyperlinks"),
make other links in documentation consistent with the preferred way.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Tested-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

[JD: Update the subject
     One more typo fixed
     Drop the link to lm-sensors' README, it's irrelevant]

Signed-off-by: Bruce Duncan <bwduncan@gmail.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

The sequence of sections is a bit confusing here:

 * we list the mux locking scheme for existing drivers before introducing
   what mux locking schemes are
 * we list the caveats for each locking scheme (which are tricky) before
   the example of the simple use case

Restructure it entirely with the following logic:

 * Intro ("I2C muxes and complex topologies")
 * Locking
   - mux-locked
     - example
     - caveats
   - parent-locked
     - example
     - caveats
 * Complex examples
 * Mux type of existing device drivers

While there, also apply some other improvements:

 * convert the caveat list from a table (with only one column carrying
   content) to a bullet list.
 * add a small introductory text to bridge the gap from listing the use
   cases to telling about the hardware components to handle them and then
   the device drivers that implement those.
 * make empty lines usage more uniform

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"Etc" here was never meant to be a heading, it became one while converting
to ReST.

It would be easy to just convert it to plain text, but rather remove it and
add an introductory text before the list that conveys the same meaning but
with a better reading flow.

Fixes: ccf988b66d69 ("docs: i2c: convert to ReST and add to driver-api bookset")
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"intension" should have probably been "intention", however "intent" seems
even better.

Reported-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Acked-by: Peter Rosin <peda@axentia.se>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

dts files cannot be linked conveniently, thus replace them with literal
formatting.

The links to other rst pages are broken, fix them using the proper syntax.

Fixes: 31df7195b100 ("Documentation: i2c: Add doc for I2C sysfs")
Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Improve wording in a couple sentences.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
[wsa: improved a little more]
Signed-off-by: Wolfram Sang <wsa@kernel.org>

These blocks can be nicely coloured via Sphinx.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

Use a more professional wording.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>

"Comm", "Count", "DataLow", "DataHigh" are not used in this section.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>