Re: [RFC Draft PATCH net-next 0/1] Bridge doc update

[Hangbin Liu <liuhangbin@gmail.com>]

On Wed, Sep 20, 2023 at 01:38:44PM +0300, Nikolay Aleksandrov wrote:
> > 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/
> > > 
> 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.

Hi Nikolay,

Thanks for the feedback. I agree that it's more reasonable to have
different docs for user-space and kernel api. As long as our bridge developers
satisfied to maintain these 2 docs at the same time, I'm totally OK to drop
this bloated convert tool.

> W.r.t the kernel doc topics covered, I think the list is a good start.

Thanks, I will add more parts and re-post it next month.

Regards
Hangbin