diff --git a/doc/contributing/docs/markup/_includes/doc-link.rst b/doc/contributing/docs/markup/_includes/doc-link.rst index 29d88976fe..92fc55fe64 100644 --- a/doc/contributing/docs/markup/_includes/doc-link.rst +++ b/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` \ No newline at end of file diff --git a/doc/contributing/docs/markup/_includes/ref-link.rst b/doc/contributing/docs/markup/_includes/ref-link.rst new file mode 100644 index 0000000000..d6cce07a65 --- /dev/null +++ b/doc/contributing/docs/markup/_includes/ref-link.rst @@ -0,0 +1 @@ +Check out the :ref:`Quick start guide `. \ No newline at end of file diff --git a/doc/contributing/docs/markup/_includes/samp.rst b/doc/contributing/docs/markup/_includes/samp.rst index 781c1e9bea..e103da9757 100644 --- a/doc/contributing/docs/markup/_includes/samp.rst +++ b/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}**})})` \ No newline at end of file diff --git a/doc/contributing/docs/markup/code.rst b/doc/contributing/docs/markup/code.rst index 8fee68697f..9380f15908 100644 --- a/doc/contributing/docs/markup/code.rst +++ b/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: diff --git a/doc/contributing/docs/markup/links.rst b/doc/contributing/docs/markup/links.rst index 5cc7b5579e..5f983ebfec 100644 --- a/doc/contributing/docs/markup/links.rst +++ b/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 ` + :doc:`box.error reference ` 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 `_. + Feel free to report an issue at `Tarantool GitHub `_. 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. \ No newline at end of file +because every separated link tends to cause troubles when this documentation +is translated to other languages. \ No newline at end of file diff --git a/doc/contributing/docs/style.rst b/doc/contributing/docs/style.rst index 9bf014f57f..8ce42ef88b 100644 --- a/doc/contributing/docs/style.rst +++ b/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 `_. -So it's best to avoid using them. \ No newline at end of file +So it's best to avoid using them. + +Specify a link text +------------------- + +While giving a :doc:`link `, specify clearly +where this link leads. Thus, you will not mislead a reader. + +Bad example: + + For more details, click :doc:`here `. + + Use :doc:`this `. + +Good example: + + For more details, refer to the documentation on + :doc:`making links `. + + Use full :doc:`link names `. \ No newline at end of file