openstack/openstack-manuals
Code Issues Proposed changes

[contributor] Update guideline of RST reference

Browse Source 
Sphinx allows separate reference definition, but it is not translator
friendly because translators cannot control links (for example,
they may want to use links to translated documents), so we recommend
not to use separate reference definitions.

This convention is already applied in reviews but not documented so far.

References:
ML discussion: http://lists.openstack.org/pipermail/openstack-docs/2015-November/007955.html
Networking guide changes: https://review.openstack.org/#/c/301265/

Change-Id: I0ed77e57f3442d962deed3fca01e7a4a7c11ab04
This commit is contained in:
Akihiro Motoki 2016-06-19 23:40:31 +09:00
parent d099f4de60
commit 9151d75cc4
1 changed files with 4 additions and 22 deletions

26
doc/contributor-guide/source/rst-conv/refs.rst

@ -40,7 +40,7 @@ but within one directory. Otherwise, use the external linking.
External references
~~~~~~~~~~~~~~~~~~~
To link to some external locations, format RST source as follows:
To link to some external locations, format the RST source as follows:
* Do not apply any markups to specify a web link.
@ -48,9 +48,9 @@ To link to some external locations, format RST source as follows:
format a web link as ``Link text <http://web-link.com>``
wrapping it in backticks.
* If a source file contains a big number of external references,
you can separate a link from its definition for better readability
while reviewing as shown in the example.
* Do not separate a link name from a link itself by defining the link in other
place in your document. It prevents translated documents from using different
links, for example, corresponding links to translated versions.
**Input**
@ -61,27 +61,9 @@ To link to some external locations, format RST source as follows:
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/
**Output**
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
Here is an external web link separated from its definition:
This paragraph contains the link to `User guide`_.
...
.. format the link definition at the end of the file as follows:
.. _`User guide`: http://docs.openstack.org/user-guide/