[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <e6b9ed8b-7044-0fab-a735-fa9cbeeb97c1@blackwall.org>
Date: Wed, 20 Sep 2023 13:38:44 +0300
From: Nikolay Aleksandrov <razor@...ckwall.org>
To: Hangbin Liu <liuhangbin@...il.com>, Roopa Prabhu <roopa@...dia.com>
Cc: "David S . Miller" <davem@...emloft.net>, netdev@...r.kernel.org,
David Ahern <dsahern@...nel.org>, Eric Dumazet <edumazet@...gle.com>,
Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
Ido Schimmel <idosch@...sch.org>,
Stephen Hemminger <stephen@...workplumber.org>
Subject: Re: [RFC Draft PATCH net-next 0/1] Bridge doc update
On 9/20/23 12:19, Hangbin Liu wrote:
> Hi Nikolay, Roopa,
>
> Do you have any comments for this RFC?
>
> Thanks
> Hangbin
> On Wed, Sep 13, 2023 at 05:28:52PM +0800, Hangbin Liu wrote:
>> Hi,
>>
>> After a long busy period. I got time to check how to update the bridge doc.
>> Here is the previous discussion we made[1].
>>
>> In this update. I plan to convert all the bridge description/comments to
>> the kernel headers. And add sphinx identifiers in the doc to show them
>> directly. At the same time, I wrote a script to convert the description
>> in kernel header file to iproute2 man doc. With this, there is no need
>> to maintain the doc in 2 places.
>>
>> For the script. I use python docutils to read the rst comments. When dump
>> the man page. I do it manually to match the current ip link man page style.
>> I tried rst2man, but the generated man doc will break the current style.
>> If you have any other better way, please tell me.
>>
>> [1] https://lore.kernel.org/netdev/5ddac447-c268-e559-a8dc-08ae3d124352@blackwall.org/
>>
>>
>> Hangbin Liu (1):
>> Doc: update bridge doc
>>
>> Documentation/networking/bridge.rst | 85 ++++++++++--
>> include/uapi/linux/if_bridge.h | 24 ++++
>> include/uapi/linux/if_link.h | 194 ++++++++++++++++++++++++++++
>> 3 files changed, 293 insertions(+), 10 deletions(-)
>>
>> --
>> 2.41.0
>>
Hi Hangbin,
I support all efforts to improve documentation, but I do share the same
concerns that Stephen has already voiced. I don't think we should be
generating the man page from the kernel docs, IMO it would be simpler
and easier for everyone to support both docs - one is for the user-space
iproute2 commands, the other could go into the kernel api details. All
attribute descriptions can still be added to headers, that would be very
valuable on its own. I prefer to have the freedom to change the docs
format in any way, generating them from comments is kind of limiting.
The purpose of each document is different and it will be difficult
to combine them for a man page. It would be much easier for everyone
to add user-related command descriptions and examples in iproute2's
documentation, and to add kernel-specific (or uapi) documentation to the
kernel doc. We can add references for each with a short description.
W.r.t the kernel doc topics covered, I think the list is a good start.
Thank you,
Nik
Powered by blists - more mailing lists