[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:
parent
5af0b3f444
commit
3c5b133b66
@ -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/
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user