On 1/5/23 21:12, Han Zhou wrote: > > > On Thu, Jan 5, 2023 at 11:42 AM Ilya Maximets <i.maxim...@ovn.org > <mailto:i.maxim...@ovn.org>> wrote: >> >> GitHub and Sphinx are parsing links differently. Sphinx knows about >> the overall documentation structure and all the sections defined in >> other docs, while GitHub is using direct rst 2 html conversion and >> doesn't know any of that. Sphinx wants links to sections in other >> docs to be defined with a :doc: field, but GitHub can't parse that >> and requires having a direct link to the other rST document. >> >> The problem is that we have a top level MAINTAINERS.rst, that should >> be parseable by GitHub, included in the maintainers.rst in the >> main documentation section that is used by Sphinx to generate html, >> pdf and other docs. So, it's hard to make links work in both. >> >> Working around that limitation by using rST substitutions for the >> links. Cutting off the substitutions for actual links and adding >> :doc: links instead during the file inclusion for Sphinx. >> >> Reported-by: Igor Zhukov <ivzhu...@sbercloud.ru >> <mailto:ivzhu...@sbercloud.ru>> >> Signed-off-by: Ilya Maximets <i.maxim...@ovn.org <mailto:i.maxim...@ovn.org>> >> --- >> Documentation/internals/maintainers.rst | 5 +++++ >> MAINTAINERS.rst | 21 +++++++++++++++------ >> 2 files changed, 20 insertions(+), 6 deletions(-) >> >> diff --git a/Documentation/internals/maintainers.rst >> b/Documentation/internals/maintainers.rst >> index 172d684df..0203bbe95 100644 >> --- a/Documentation/internals/maintainers.rst >> +++ b/Documentation/internals/maintainers.rst >> @@ -22,3 +22,8 @@ >> Avoid deeper levels because they do not render well. >> >> .. include:: ../../MAINTAINERS.rst >> + :end-before: Cut here for the Documentation/internals/maintainers.rst >> + >> +.. |responsibilities| replace:: :doc:`committer-responsibilities` >> +.. |grant-revocation| replace:: :doc:`committer-grant-revocation` >> +.. |emeritus-status| replace:: :doc:`committer-emeritus-status` >> diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst >> index 27be4aa41..1dc406170 100644 >> --- a/MAINTAINERS.rst >> +++ b/MAINTAINERS.rst >> @@ -28,11 +28,11 @@ Committers >> Open vSwitch committers are the people who have been granted access to push >> changes to the Open vSwitch git repository. >> >> -The responsibilities of an Open vSwitch committer are documented >> -`here <Documentation/internals/committer-responsibilities.rst>`__. >> +The responsibilities of an Open vSwitch committer are documented here: >> +|responsibilities|. >> >> -The process for adding or removing committers is documented >> -`here <Documentation/internals/committer-grant-revocation.rst>`__. >> +The process for adding or removing committers is documented here: >> +|grant-revocation|. >> >> This is the current list of active Open vSwitch committers: >> >> @@ -77,8 +77,8 @@ This is the current list of active Open vSwitch committers: >> - yamam...@midokura.com <mailto:yamam...@midokura.com> >> >> The project also maintains a list of Emeritus Committers (or Maintainers). >> -More information about Emeritus Committers can be found >> -`here <Documentation/internals/committer-emeritus-status.rst>`__. >> +More information about Emeritus Committers can be found here: >> +|emeritus-status|. >> >> .. list-table:: OVS Emeritus Maintainers >> :header-rows: 1 >> @@ -91,3 +91,12 @@ More information about Emeritus Committers can be found >> - e...@eecs.berkeley.edu <mailto:e...@eecs.berkeley.edu> >> * - Joe Stringer >> - j...@ovn.org <mailto:j...@ovn.org> >> + >> +.. Cut here for the Documentation/internals/maintainers.rst >> + >> +.. |responsibilities| replace:: `Expectations for Developers with Open >> vSwitch >> + Repo Access <Documentation/internals/committer-responsibilities.rst>`__ >> +.. |grant-revocation| replace:: `OVS Committer Grant/Revocation Policy >> + <Documentation/internals/committer-grant-revocation.rst>`__ >> +.. |emeritus-status| replace:: `Emeritus Status for OVS Committers >> + <Documentation/internals/committer-emeritus-status.rst>`__ >> -- >> 2.38.1 >> > > Thanks Ilya, this is brilliant. > Acked-by: Han Zhou <hz...@ovn.org <mailto:hz...@ovn.org>>
Thanks! I'll apply the change to OVS a bit later today. > > Would you mind sending the same for OVN (almost the same but the diff > doesn't work directly because the offsets are different in the OVN file)? Sure, will send an OVN version. Best regards, Ilya Maximets. _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
