mirror of
https://github.com/openvswitch/ovs
synced 2025-08-30 22:05:19 +00:00
a7826d05b8
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 <ivzhukov@sbercloud.ru> Acked-by: Han Zhou <hzhou@ovn.org> Acked-by: Eelco Chaudron <echaudro@redhat.com> Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
30 lines
1.2 KiB
ReStructuredText
30 lines
1.2 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
Convention for heading levels in Open vSwitch documentation:
|
|
|
|
======= Heading 0 (reserved for the title in a document)
|
|
------- Heading 1
|
|
~~~~~~~ Heading 2
|
|
+++++++ Heading 3
|
|
''''''' Heading 4
|
|
|
|
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`
|