On 4/28/26 8:36 PM, Ilya Maximets wrote:
> On 4/28/26 7:45 PM, Mark Michelson via dev wrote:
>> This patch set aims to correct errors in ovn-northd documentation.
>> Specifially, it corrects the following:
>>
>> * Add missing/incorrect program options to manpages. For this series,
>> this includes the ovn-northd, ovn-nb, and ovn-nbctl manpages.
>> * Correct missing/incorrect program options in usage strings. For this
>> series, this includes the ovn-northd and ovn-nbctl programs.
>>
>> In addition to the above, this series also splits the ovn-northd manpage
>> in two. The ovn-northd manpage contains only information about running
>> the ovn-northd application, such as command line options. The new
>> ovn-logical-flows manpage contains information about the logical flows
>> that ovn-northd installs. The final commit in this series converts the
>> ovn-logical-flows manpage input file from XML to rST, since it is more
>> frequently updated by developers, and rST is much easier to read and
>> edit than XML.
>>
>> One thing this series does NOT try to address is missing information in
>> the ovn-logical-flows document regarding how certain options affect the
>> generated logical flows. This can be done in another patch series, and
>> with the conversion to rST, this will likely be much easier to do.
>>
>> About 99% of this series was AI-generated. My contributions are some
>> clarifications in the commit messages, as well as updating some
>> ancillary files in the final commit to indicate the requirement for
>> rst2man.
>
> FWIW, we shouldn't add an extra dependency for this. The standard way to
> build rST man pages is with sphinx and OVN already has all the infra for
> that in Documentation/automake.mk. The ovn-sim.1 is built this way.
> Though you'll need to use RST_MANPAGES instead of RST_MANPAGES_NOINST for
> the northd page, I suppose. You can also find more examples in the
> Documentation/automake.mk in OVS.
There is also this commit where I converted ovs-actions page from XML
to rST quite a few years ago (in OVS repo, of course):
c2fb5bdae6e3 ("ovs-actions: Convert man page from xml to rST.")
It's not perfect, but can be used as a reference.
>
> The resulted page will be in Documentation/ref, make sure it's properly
> placed for distribution. Will need an update for Documentation/conf.py
> and Documentation/ref/index.rst, so it is browse-able in the built
> documentation on the website.
>
> And maybe tell claude to respect the ling length limits where it's not
> a vebratim code. :)
This last remark is primarily for over-wrapping. The line lengths in the
new rST doc are all over the place in terms of their length, it's actually
hard to read. The doc can be likely significantly shorter, if the lines
are wrapped proerply. E.g. this:
+ - If the logical router has rules specified in
+ ``nat`` with
+ ``external_mac``, then
+ those addresses are also used to populate the switch's destination
+ lookup on the chassis where
+ ``logical_port`` is
+ resident.
Can probably be about 3 lines instead of 7.
It also sometimes splits the `` `` blocks, sometimes it doesn't. In a few
places it might be more beneficial to use proper blocks with :: instead of
very long `` `` lines.
In general, while claude made a bulk of work, I'd suggest to do a manual
editing run. It sucks, but the doc can be much better with proper formatting,
highlights and section cross-reference (I don't see links between sections
in the patch, while they can be there, since rST allows for this kind of
stuff) that will be very useful in html on the website. Maybe claude can
help with this stuff too, but it needs to be guided.
Best regards, Ilya Maximets.
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
