[Contributor Guide] RST references

1. Adds the Reference section to the rst chapter
2. Removes outputs of some code-blocks formatting to remove
   line numbering further in the section

Implements: blueprint docs-contributor-guide
Change-Id: I0ebe9e34625c09bf9f1466158312b2c5b81de5ff
This commit is contained in:
OlgaGusarenko 2015-08-31 13:31:17 +03:00 committed by Olga Gusarenko
parent 5af0b3f444
commit 3c5b133b66

View File

@ -40,6 +40,8 @@ Space and tab characters
the checkniceness test will fail because of the trailing whitespaces.
.. _cg_titles:
Titles
~~~~~~
@ -188,25 +190,6 @@ than 5 lines.
| ... | ... |
+-----------------+--------------------------+
**Output**
.. highlight:: console
:linenothreshold: 5
This is the file body with the code snippet within:
::
$ neutron ext-list -c alias -c name
+-----------------+--------------------------+
| alias | name |
+-----------------+--------------------------+
| agent_scheduler | Agent Schedulers |
| binding | Port Binding |
| quotas | Quota management support |
| ... | ... |
+-----------------+--------------------------+
Non-standard literal block
--------------------------
@ -241,30 +224,99 @@ emphasize.
.. code::
.. code-block:: ini
:emphasize-lines: 1, 5-7
:linenos:
:emphasize-lines: 1, 4
# Configuration for nova-rootwrap
# This file should be owned by (and only-writeable by) the root user
[DEFAULT]
# List of directories to load filter definitions from (separated by ',').
# These directories MUST all be only writeable by root !
filters_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap
References
~~~~~~~~~~
Cross-references
----------------
To cross-reference to arbitrary locations within one document,
use the ``ref`` role:
**Input**
.. code::
.. _cg_titles:
Titles
~~~~~~
This is the section we want to reference to.
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
**Output**
...
The following - :ref:`cg_titles` - generates a link to the section with
the defined label using this section heading as a link title.
A link label and a reference can be defined in separate source files,
but within one directory. Otherwise, use the external linking.
External references
-------------------
To link to some external locations, format RST source as follows:
#. Do not apply any markups to specify a web link.
#. If you need a specific link title to appear in the output,
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.
**Input**
.. code::
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/
**Output**
.. code-block:: ini
:emphasize-lines: 1, 5-7
:linenos:
Here is a link to the User guide: http://docs.openstack.org/user-guide/.
# Configuration for nova-rootwrap
# This file should be owned by (and only-writeable by) the root user
Here is an external web link with a link title:
`User guide <http://docs.openstack.org/user-guide/>`_.
[DEFAULT]
# List of directories to load filter definitions from (separated by ',').
# These directories MUST all be only writeable by root !
filters_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap
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/