From: Luca Ceresoli <luca@lucaceresoli.net>
To: Jean Delvare <jdelvare@suse.de>
Cc: linux-doc@vger.kernel.org, linux-i2c@vger.kernel.org,
Wolfram Sang <wsa@the-dreams.de>, Peter Rosin <peda@axentia.se>,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 01/26] docs: i2c: sort index logically
Date: Mon, 20 Jan 2020 14:56:18 +0100 [thread overview]
Message-ID: <9073e6c2-1f82-6067-0d2a-3e8d32dca89a@lucaceresoli.net> (raw)
In-Reply-To: <e5d3656d-04a1-dd1b-e847-fb063e56a987@lucaceresoli.net>
Hi,
On 20/01/20 10:22, Luca Ceresoli wrote:
> Hi Jean,
>
> On 20/01/20 10:08, Jean Delvare wrote:
>> Hi Luca,
>>
>> On Sun, 5 Jan 2020 23:49:47 +0100, Luca Ceresoli wrote:
>>> The index page currently lists sections in alphabetical file order without
>>> caring about their content. Sort sections based on their content logically,
>>> according to the following structure:
>>>
>>> * Intro to I2C/SMBus and their usage in Linux: summary, i2c-protocol,
>>> smbus-protocol, instantiating-devices, busses/index, i2c-topology,
>>> muxes/i2c-mux-gpio
>>> * Implementing drivers: writing-clients, dev-interface,
>>> dma-considerations, fault-codes, functionality
>>> * Debugging: gpio-fault-injection, i2c-stub
>>> * Slave I2C: slave-interface, slave-eeprom-backend
>>> * Advanced: ten-bit-addresses
>>> * Obsolete info: upgrading-clients, old-module-parameters
>>
>> Good idea. I wonder, would there be a way to materialize these group
>> names in the documentation itself? I found it useful when reviewing the
>> patch, but in the long term it would be even more useful if the end
>> readers would see them too.
>
> I had the same idea, but didn't find an obvious way to do it with the
> ReST/Sphynx syntax. I have also browsed through a few index pages for
> other subsystems and they all have a flat list too, so for the moment I
> gave up.
The best way I could find is in Documentation/core-api/index.rst
(https://www.kernel.org/doc/html/latest/core-api/index.html). I don't
like very much how the .rst source looks like, but AFAICT this seems
like "the" way of doing it.
Unless there are better options, I'll try this syntax in v2.
--
Luca
next prev parent reply other threads:[~2020-01-20 13:56 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-05 22:39 [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
2020-01-05 22:49 ` [PATCH 01/26] docs: i2c: sort index logically Luca Ceresoli
2020-01-05 22:49 ` [PATCH 02/26] docs: i2c: summary: extend introduction Luca Ceresoli
2020-01-20 9:27 ` Jean Delvare
2020-01-20 21:54 ` Luca Ceresoli
2020-01-05 22:49 ` [PATCH 03/26] docs: i2c: summary: rewrite the "terminology" section Luca Ceresoli
2020-01-20 10:04 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 04/26] docs: i2c: call it "I2C" consistently Luca Ceresoli
2020-01-07 10:33 ` Peter Rosin
2020-01-16 9:39 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 05/26] docs: i2c: fix typo Luca Ceresoli
2020-01-07 10:33 ` Peter Rosin
2020-01-16 9:40 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 06/26] docs: i2c: replace "I2C-transfer" -> "I2C transfer" consistently Luca Ceresoli
2020-01-07 10:34 ` Peter Rosin
2020-01-20 10:07 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 07/26] docs: i2c: i2c-protocol: fix kernel-doc function syntax Luca Ceresoli
2020-01-20 10:51 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 08/26] docs: i2c: i2c-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 12:49 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 09/26] docs: i2c: i2c-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 13:38 ` Jean Delvare
2020-01-20 14:22 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 10/26] docs: i2c: i2c-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 13:50 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 11/26] docs: i2c: smbus: fix link syntax Luca Ceresoli
2020-01-20 14:10 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 12/26] docs: i2c: smbus-protocol: properly name start and stop conditions Luca Ceresoli
2020-01-20 14:16 ` Jean Delvare
2020-01-05 22:49 ` [PATCH 13/26] docs: i2c: smbus-protocol: remove unneeded colons from table Luca Ceresoli
2020-01-20 14:23 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 14/26] docs: i2c: smbus-protocol: use proper names for ACK and NACK Luca Ceresoli
2020-01-20 14:26 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 15/26] docs: i2c: smbus-protocol: enable kernel-doc function syntax Luca Ceresoli
2020-01-20 14:44 ` Jean Delvare
2020-01-21 17:31 ` Luca Ceresoli
2020-01-22 11:48 ` Jean Delvare
2020-01-23 9:51 ` Luca Ceresoli
2020-01-22 14:26 ` Jean Delvare
2020-01-22 15:37 ` Wolfram Sang
2020-01-23 9:51 ` Luca Ceresoli
2020-01-05 22:50 ` [PATCH 16/26] docs: i2c: smbus-protocol: fix " Luca Ceresoli
2020-01-20 14:51 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 17/26] docs: i2c: i2c-protocol: fix typo Luca Ceresoli
2020-01-20 15:15 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 18/26] docs: i2c: i2c-protocol: fix punctuation Luca Ceresoli
2020-01-20 15:16 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 19/26] docs: i2c: smbus-protocol: improve I2C Block transactions description Luca Ceresoli
2020-01-21 9:16 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 20/26] docs: i2c: instantiating-devices: fix internal hyperlink Luca Ceresoli
2020-01-21 10:07 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 21/26] docs: i2c: instantiating-devices: rearrange static instatiation Luca Ceresoli
2020-01-21 18:02 ` Jean Delvare
2020-01-23 9:51 ` Luca Ceresoli
2020-01-05 22:50 ` [PATCH 22/26] docs: i2c: instantiating-devices: use monospace for filenames Luca Ceresoli
2020-01-22 10:08 ` Jean Delvare
2020-01-05 22:50 ` [PATCH 23/26] docs: i2c: old-module-parameters: fix internal hyperlink Luca Ceresoli
2020-01-22 10:16 ` Jean Delvare
2020-01-23 9:50 ` Luca Ceresoli
2020-01-20 9:08 ` [PATCH 01/26] docs: i2c: sort index logically Jean Delvare
2020-01-20 9:22 ` Luca Ceresoli
2020-01-20 13:56 ` Luca Ceresoli [this message]
2020-01-06 7:46 ` [PATCH 24/26] docs: i2c: old-module-parameters: clarify this is for obsolete kernels Luca Ceresoli
2020-01-22 11:18 ` Jean Delvare
2020-01-06 7:46 ` [PATCH 25/26] docs: i2c: old-module-parameters: use monospace for filenames Luca Ceresoli
2020-01-22 11:45 ` Jean Delvare
2020-01-06 7:49 ` [PATCH 26/26] docs: i2c: rename sections so the overall picture is clearer Luca Ceresoli
2020-01-07 10:36 ` Peter Rosin
2020-01-16 9:49 ` Jean Delvare
2020-01-16 10:38 ` Luca Ceresoli
2020-01-16 13:34 ` Peter Rosin
2020-01-06 8:03 ` [PATCH 00/26] docs: i2c: rework I2C documentation, part I Luca Ceresoli
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9073e6c2-1f82-6067-0d2a-3e8d32dca89a@lucaceresoli.net \
--to=luca@lucaceresoli.net \
--cc=jdelvare@suse.de \
--cc=linux-doc@vger.kernel.org \
--cc=linux-i2c@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=peda@axentia.se \
--cc=wsa@the-dreams.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).