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

On Wed, Sep 13, 2023 at 04:22:24AM -0700, Stephen Hemminger wrote:

On Wed, 13 Sep 2023 17:28:52 +0800
Hangbin Liu [off-list ref] wrote:

quoted

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/ (local)


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(-)

Not sure this is good idea.
- you are special casing bridge documentation and there is lots of
  other parts of iproute2

   Yes, the patch's purpose is to save the work for bridge doc(at present).
   So only the bridge part of iproute2 man page will be updated. I added a
   tag at the start/end of the bridge part. Other parts will not be touched.

- you are introducing a dependency on python in iproute2

    There is no need to build it. I put it in the tools folder. Any one can
    choose to use or not use it. So I don't think it count for dependency.

- the kernel headers in iproute2 come from sanitized kernel headers. So
  fixing the documentation would take longer.

    It doesn't matter. The python script only grab the attr description from
    net-next and convert it to man doc. It doesn't care about the kernel
    header in iproute2.

What problem is this trying to solve?

The bridge doc in kernel[1] is too old. There are a lot of details hide in
the kernel code and new developer is hard to catch up. So the kernel bridge
doc page need an update. 

You could say the iproute2 bridge documentation is new and updated. We can
take it as the new bridge doc. But iprotue2 bridge doc only contains uAPI.
The kernel API doc is still needed.

On the other hand, the bridge developers already speed a lot effort on iproute2
bridge documentation. It would introduce more work and complex to maintain
the kernel and bridge doc at the same time.

So I suggest to only maintain the kernel doc. And convert the kernel part
directly to iproute2 man page. With this, we can maintain the doc in one
place and update them both on kernel and iproute2.

[1] https://www.kernel.org/doc/Documentation/networking/bridge.rst

Thanks
Hangbin