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 <[email protected]> Signed-off-by: Ilya Maximets <[email protected]> --- 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: - [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: 0 +.. list-table:: OVN Emeritus Maintainers + :header-rows: 1 * - Name - Email * - Ben Pfaff - [email protected] + +.. 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 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
