Documentation: Fix links in maintainers.rst.

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]>
Acked-by: Han Zhou <[email protected]>
Acked-by: Eelco Chaudron <[email protected]>
Signed-off-by: Ilya Maximets <[email protected]>

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`

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>`__