Documentation guidelines updates (#2075)

* fixes gh-1881 document extsamp role

* fixes gh-1836 add note about specifying link names

Author: Onvember

doc/contributing/docs/markup/_includes/doc-link.rst

@@ -1,4 +1 @@
-
-*   :doc:`/reference/reference_lua/box_index`
-*   :doc:`/reference/reference_lua/box_error`
-*   :doc:`/reference/reference_lua/box_backup`
+:doc:`/reference/reference_lua/box_index`

doc/contributing/docs/markup/_includes/ref-link.rst

@@ -0,0 +1 @@
+Check out the :ref:`Quick start guide <vshard-quick-start>`.

doc/contributing/docs/markup/_includes/samp.rst

@@ -1 +1,3 @@
-:samp:`{space_object}:insert`:code:`({ffi.cast('double',`:samp:`{value}`:code:`)})`
+:samp:`{space_object}:insert(\\{ffi.cast('double', {value})\\})`
+
+:extsamp:`{*{space_object}*}:insert({ffi.cast('double', {**{value}**})})`

doc/contributing/docs/markup/code.rst

@@ -114,8 +114,8 @@ Notes on using inline-code
 Highlighting variables in code
 ------------------------------
 
-If you need to mark up a placeholder inside code inline, use the ``:samp:``
-role, like this:
+If you need to mark up a placeholder inside code inline, use the ``:samp:`` or
+our custom ``:extsamp:`` role, like this:
 
     ..  literalinclude:: _includes/samp.rst
         :language: rst
@@ -124,6 +124,17 @@ And you will get this:
 
     ..  include:: _includes/samp.rst
 
+Notice two backslashes before the curly brackets in the first line.
+They are needed to escape curly brackets from Lua syntax.
+
+As you can see, ``:extsamp:`` extends the abilities of ``:samp:``.
+It allows you to highlight placeholders in both italics and bold
+and avoid escaping curly brackets.
+``:extsamp:`` has the following syntax:
+
+*   ``{*{element}*}`` for *italic*
+*   ``{**{element}**}`` for **bold**
+
 If you need to mark up a placeholder in code block, use
 the following syntax:
 

doc/contributing/docs/markup/links.rst

@@ -7,9 +7,9 @@ Linking to other documentation pages
 To create a link to another document in our documentation, we use the ``:doc:`` role.
 For example, this link points to the document ``/reference/reference_lua/box_error.rst``:
 
-..  code-block:: rst
+    ..  code-block:: rst
 
-    :doc:`box.error reference </reference/reference_lua/box_error>`
+        :doc:`box.error reference </reference/reference_lua/box_error>`
 
 Our convention is to put the full path to the referred document so that we can
 easily replace the path if it changes.
@@ -18,12 +18,12 @@ Note that we can omit the ``.rst`` part of the filename.
 You can use the target document's title as the link text.
 To do so, omit the text in the link definition:
 
-..  literalinclude:: _includes/doc-link.rst
-    :language: rst
+    ..  literalinclude:: _includes/doc-link.rst
+        :language: rst
 
 And you will get this:
 
-..  include:: _includes/doc-link.rst
+    ..  include:: _includes/doc-link.rst
 
 Linking to labels (anchors)
 ---------------------------
@@ -56,24 +56,33 @@ The tag can be anything meaningful. The only guideline is for Tarantool syntax
 items (such as members), where the preferred tag syntax is
 ``module_or_object_name dash member_name``. For example, ``box_space-drop``.
 
+To add a link to an anchor, use the following syntax:
+
+    ..  literalinclude:: _includes/ref-link.rst
+        :language: rst
+
+The result will be like this:
+
+    ..  include:: _includes/ref-link.rst
+
 Linking to external resources
 -----------------------------
 
 To make an external link, use the following syntax:
 
-..  code-block:: text
+    ..  code-block:: text
 
-    This is a paragraph that contains `a link <http://example.com/>`_.
+        Feel free to report an issue at `Tarantool GitHub <https://github.com/tarantool/tarantool/issues>`_.
 
 Avoid separating the link and the target definition, like this:
 
-..  container:: dont
+    ..  container:: dont
 
-    ..  code-block:: rst
+        ..  code-block:: rst
 
-        This is wrong way to make `a link`_.
+            Feel free to report an issue at `Tarantool GitHub`_.
 
-        ..  _a link: http://example.com/
+            ..  _Tarantool GitHub: https://github.com/tarantool/tarantool/issues
 
-**Warning:** Every separated link tends to cause troubles when this documentation
-is translated to other languages. Please avoid using separated links.
+because every separated link tends to cause troubles when this documentation
+is translated to other languages.

doc/contributing/docs/style.rst

@@ -1,17 +1,14 @@
 
-================================================================================
 Language and style
-================================================================================
+==================
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 US vs British spelling
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 We use English US spelling.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Instance vs server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------
 
 We say "instance" rather than "server" to refer to an instance of Tarantool
 server. This keeps the manual terminology consistent with names like
@@ -23,10 +20,8 @@ of the same databases."
 Correct usage: "Replication allows multiple Tarantool *instances* to work on
 copies of the same databases."
 
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Express one idea in a sentence
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Say exactly one thing in a sentence.
 If you want to define or clarify something, do it in a separate sentence.
@@ -61,9 +56,8 @@ Simple sentences are easier to read, understand and translate.
             -   A replica set from which the bucket is being migrated is called a source.
                 A target replica set to which the bucket is being migrated is called a destination.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Don't use i.e. and e.g.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 Don't use the following contractions:
 
@@ -76,4 +70,23 @@ Many people, especially non-native English speakers,
 aren't familiar or don't know the difference between
 `"i.e." and "e.g." contractions
 <https://www.merriam-webster.com/words-at-play/ie-vs-eg-abbreviation-meaning-usage-difference>`_.
-So it's best to avoid using them.
+So it's best to avoid using them.
+
+Specify a link text
+-------------------
+
+While giving a :doc:`link </contributing/docs/markup/links>`, specify clearly
+where this link leads. Thus, you will not mislead a reader.
+
+Bad example:
+
+    For more details, click :doc:`here </contributing/docs/markup/links>`.
+
+    Use :doc:`this </contributing/docs/markup/links>`.
+
+Good example:
+
+    For more details, refer to the documentation on
+    :doc:`making links </contributing/docs/markup/links>`.
+
+    Use full :doc:`link names </contributing/docs/markup/links>`.