On Fri, Jan 6, 2023 at 3:55 AM Ilya Maximets <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. > > While at it, also fixing table names (s/OVS/OVN/). > > Reported-by: Igor Zhukov <ivzhu...@sbercloud.ru> > Signed-off-by: Ilya Maximets <i.maxim...@ovn.org> > --- > Documentation/internals/maintainers.rst | 5 +++++ > MAINTAINERS.rst | 27 ++++++++++++++++--------- > 2 files changed, 23 insertions(+), 9 deletions(-) > > diff --git a/Documentation/internals/maintainers.rst b/Documentation/internals/maintainers.rst > index 5d4af3f5f..dbe55cd70 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 a4012a5cf..23dcbbbad 100644 > --- a/MAINTAINERS.rst > +++ b/MAINTAINERS.rst > @@ -28,15 +28,15 @@ Committers > OVN committers are the people who have been granted access to push > changes to to the OVN git repository. > > -The responsibilities of an OVN committer are documented > -`here <Documentation/internals/committer-responsibilities.rst>`__. > +The responsibilities of an OVN 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 OVN committers: > > -.. list-table:: OVS Maintainers > +.. list-table:: OVN Maintainers > :header-rows: 1 > > * - Name > @@ -59,13 +59,22 @@ This is the current list of active OVN committers: > - russ...@ovn.org > > 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: 0 > +.. list-table:: OVN Emeritus Maintainers > + :header-rows: 1 > > * - Name > - Email > * - Ben Pfaff > - b...@ovn.org > + > +.. Cut here for the Documentation/internals/maintainers.rst > + > +.. |responsibilities| replace:: `Expectations for Developers with OVN Repo > + Access <Documentation/internals/committer-responsibilities.rst>`__ > +.. |grant-revocation| replace:: `OVN Committer Grant/Revocation Policy > + <Documentation/internals/committer-grant-revocation.rst>`__ > +.. |emeritus-status| replace:: `Emeritus Status for OVN Committers > + <Documentation/internals/committer-emeritus-status.rst>`__ > -- > 2.38.1 >
Thanks Ilya, Igor and Mark. I applied this to main. Han _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
