On 1/5/23 21:12, Han Zhou wrote: > > > On Thu, Jan 5, 2023 at 11:42 AM Ilya Maximets <[email protected] > <mailto:[email protected]>> 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 <[email protected] >> <mailto:[email protected]>> >> Signed-off-by: Ilya Maximets <[email protected] <mailto:[email protected]>> >> --- >> 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: >> - [email protected] <mailto:[email protected]> >> >> 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 >> - [email protected] <mailto:[email protected]> >> * - Joe Stringer >> - [email protected] <mailto:[email protected]> >> + >> +.. 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 <[email protected] <mailto:[email protected]>>
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 [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
