On Thu, Jan 5, 2023 at 11:42 AM Ilya Maximets <[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]> > Signed-off-by: Ilya Maximets <[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] > > 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] > * - Joe Stringer > - [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]> 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)? Thanks, Han _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
