Updated from openstack-manuals

Also add conventions file to our manuals to explain conventions.

Change-Id: I4cc6112b520aea647ac8b285358b7a73e99dfcb5

common-rst/conventions.rst

@@ -0,0 +1,40 @@
+===========
+Conventions
+===========
+
+The OpenStack documentation uses several typesetting conventions.
+
+Notices
+~~~~~~~
+
+Notices take these forms:
+
+.. note:: A comment with additional information that explains a part of the
+          text.
+
+.. important:: Something you must be aware of before proceeding.
+
+.. tip:: An extra but helpful piece of practical advice.
+
+.. caution:: Helpful information that prevents the user from making mistakes.
+
+.. warning:: Critical information about the risk of data loss or security
+             issues.
+
+Command prompts
+~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+   $ command
+
+Any user, including the ``root`` user, can run commands that are
+prefixed with the ``$`` prompt.
+
+.. code-block:: console
+
+   # command
+
+The ``root`` user must run commands that are prefixed with the ``#``
+prompt. You can also prefix these commands with the :command:`sudo`
+command, if available, to run them.

firstapp/source/index.rst

@@ -8,6 +8,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   common/conventions.rst
    getting_started
    introduction
    scaling_out