Fix documentation build warnings (#1401)

CHANGELOG.rst

@@ -36,10 +36,10 @@ Added
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Update vshard to 0.1.17.
-  (`Changelog <https://github.com/tarantool/vshard/releases/tag/0.1.17>`_).
+  (`Changelog <https://github.com/tarantool/vshard/releases/tag/0.1.17>`__).
 
 - Update graphql to 0.1.1.
-  (`Changelog <https://github.com/tarantool/graphql/releases/tag/0.1.1>`_).
+  (`Changelog <https://github.com/tarantool/graphql/releases/tag/0.1.1>`__).
 
 - New test helper: ``cartridge.test-helpers.stateboard``.
 
@@ -431,7 +431,7 @@ Fixed
 
 - Properly handle nested input object in GraphQL:
 
-  .. code-block:: graphql
+  .. code-block:: text
 
       mutation($uuid: String!) {
         cluster { edit_topology(servers: [{uuid: $uuid ...}]) {} }

CONTRIBUTING.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ================================================================================
 Contributing
 ================================================================================

README.rst

@@ -102,9 +102,9 @@ To get a template application that uses Tarantool Cartridge and run it,
 you need to install several packages:
 
 * ``tarantool`` and ``tarantool-dev``
-  (see these `instructions <https://www.tarantool.io/en/download/>`_);
+  (see these `instructions <https://www.tarantool.io/en/download/>`__);
 * ``cartridge-cli``
-  (see these `instructions <https://github.com/tarantool/cartridge-cli#installation>`_)
+  (see these `instructions <https://github.com/tarantool/cartridge-cli#installation>`__)
 * ``git``, ``gcc``, ``cmake`` and ``make``.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -127,7 +127,6 @@ Admin Web UI:
 
 .. image:: https://user-images.githubusercontent.com/32142520/109290877-3d30a800-7839-11eb-8fcf-8b3de1237a3b.png
    :align: center
-   :scale: 100%
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Next steps

rst/LuaLexer.py

@@ -0,0 +1,133 @@
+from pygments.lexer import RegexLexer, include, bygroups, combined
+from pygments.token import Text, Comment, Operator, Keyword, Name, String
+from pygments.token import Number, Punctuation
+from pygments.util import get_bool_opt, get_list_opt
+
+__all__ = ['LuaLexer']
+
+
+class LuaLexer(RegexLexer):
+    """
+    For `Lua <http://www.lua.org>`_ source code.
+
+    Additional options accepted:
+
+    `func_name_highlighting`
+        If given and ``True``, highlight builtin function names
+        (default: ``True``).
+    `disabled_modules`
+        If given, must be a list of module names whose function names
+        should not be highlighted. By default all modules are highlighted.
+
+        To get a list of allowed modules have a look into the
+        `_luabuiltins` module:
+
+        .. sourcecode:: pycon
+
+            >>> from pygments.lexers._luabuiltins import MODULES
+            >>> MODULES.keys()
+            ['string', 'coroutine', 'modules', 'io', 'basic', ...]
+    """
+
+    name = 'lua_tarantool'
+    aliases = ['lua_tarantool']
+    filenames = ['*.lua', '*.wlua']
+    mimetypes = ['text/x-lua', 'application/x-lua']
+
+    tokens = {
+        'root': [
+            # lua allows a file to start with a shebang
+            (r'#!(.*?)$', Comment.Preproc),
+            (r'', Text, 'base'),
+        ],
+        'base': [
+            (r'(?s)--\[(=*)\[.*?\]\1\]', Comment.Multiline),
+            ('--.*$', Comment.Single),
+
+            (r'(?i)(\d*\.\d+|\d+\.\d*)(e[+-]?\d+)?', Number.Float),
+            (r'(?i)\d+e[+-]?\d+', Number.Float),
+            ('(?i)0x[0-9a-f]*', Number.Hex),
+            (r'\d+', Number.Integer),
+
+            (r'\n', Text),
+            (r'[^\S\n]', Text),
+            # multiline strings
+            (r'(?s)\[(=*)\[.*?\]\1\]', String),
+
+            (r'(==|~=|<=|>=|\.\.\.|\.\.|[=+\-*/%^<>#])', Operator),
+            (r'[\[\]\{\}\(\)\.,:;!]', Punctuation),
+            (r'(and|or|not)\b', Operator.Word),
+
+            ('(break|do|else|elseif|end|for|if|in|repeat|return|then|until|'
+             r'while)\b', Keyword),
+            (r'(local)\b', Keyword.Declaration),
+            (r'(true|false|nil)\b', Keyword.Constant),
+
+            (r'(function)\b', Keyword, 'funcname'),
+
+            (r'[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?', Name),
+
+            ("'", String.Single, combined('stringescape', 'sqs')),
+            ('"', String.Double, combined('stringescape', 'dqs'))
+        ],
+
+        'funcname': [
+            (r'\s+', Text),
+            ('(?:([A-Za-z_][A-Za-z0-9_]*)(\.))?([A-Za-z_][A-Za-z0-9_]*)',
+             bygroups(Name.Class, Punctuation, Name.Function), '#pop'),
+            # inline function
+            ('\(', Punctuation, '#pop'),
+        ],
+
+        # if I understand correctly, every character is valid in a lua string,
+        # so this state is only for later corrections
+        'string': [
+            ('.', String)
+        ],
+
+        'stringescape': [
+            (r'''\\([abfnrtv\\"']|\d{1,3})''', String.Escape)
+        ],
+
+        'sqs': [
+            ("'", String, '#pop'),
+            include('string')
+        ],
+
+        'dqs': [
+            ('"', String, '#pop'),
+            include('string')
+        ]
+    }
+
+    def __init__(self, **options):
+        self.func_name_highlighting = get_bool_opt(
+            options, 'func_name_highlighting', True)
+        self.disabled_modules = get_list_opt(options, 'disabled_modules', [])
+
+        self._functions = set()
+        if self.func_name_highlighting:
+            from pygments.lexers._lua_builtins import MODULES
+            for mod, func in MODULES.items():
+                if mod not in self.disabled_modules:
+                    self._functions.update(func)
+        RegexLexer.__init__(self, **options)
+
+    def get_tokens_unprocessed(self, text):
+        for index, token, value in \
+                RegexLexer.get_tokens_unprocessed(self, text):
+            if token is Name:
+                if value in self._functions:
+                    yield index, Name.Builtin, value
+                    continue
+                elif '.' in value:
+                    a, b = value.split('.')
+                    yield index, Name, a
+                    yield index + len(a), Punctuation, u'.'
+                    yield index + len(a) + 1, Name, b
+                    continue
+            yield index, token, value
+
+
+def setup(app):
+    app.add_lexer("lua_tarantool", LuaLexer())

rst/TarantoolSessionLexer.py

@@ -0,0 +1,174 @@
+# -*- coding: utf-8 -*-
+
+from pygments.lexer import Lexer, RegexLexer, include, bygroups, using, \
+    default, words, combined, do_insertions
+from pygments.util import get_bool_opt, shebang_matches
+from pygments.token import Text, Comment, Operator, Keyword, Name, String, \
+    Number, Punctuation, Generic, Other, Error
+from pygments import unistring as uni
+
+from LuaLexer import LuaLexer
+from pygments.lexers import YamlLexer, BashSessionLexer
+
+import re
+
+__all__ = ['TarantoolSessionLexer']
+
+line_re = re.compile('.*?\n')
+
+yml_beg = u"---"
+yml_end = u"..."
+
+uriverify = re.compile(
+#    r'^(?:http|ftp)s?://' # http:// or https://
+    r'^'
+    r'(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+(?:[A-Z]{2,6}\.?|[A-Z0-9-]{2,}\.?)|' #domain...
+    r'localhost|' # localhost...
+    r'tarantool|' # OR tarantool, we're tarantool, of course
+    r'\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})' # ...or ip
+    r'(?::\d+)?' # optional port
+    r'(?:/?|[/?]\S+)$', re.IGNORECASE
+)
+
+def find_prompt(line):
+    pos = line.find('> ')
+    if pos != -1 and uriverify.match(line[:pos]):
+        return pos
+    return False
+
+class TarantoolSessionLexer(Lexer):
+    """
+    For Tarantol session output:
+
+    .. sourcecode:: tarantoolsession
+
+        $ <bash session - preparations>
+        tarantool> ...
+                 > ...
+        ---
+        - yml_output
+        ...
+    """
+
+    name = "Tarantool console session"
+    aliases = ["tarantoolsession", "tntses"]
+    mimetypes = ['text/x-tarantool-session']
+
+    def __init__(self, **options):
+        super(TarantoolSessionLexer, self).__init__()
+
+    def get_tokens_unprocessed(self, text):
+        lualexer = LuaLexer(**self.options)
+        ymllexer = YamlLexer(**self.options)
+        shslexer = BashSessionLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        code = False
+        prompt_len = 0
+
+        curyml = ''
+        yml = False
+        ymlcnt = 0
+
+        curshs = ''
+        shs = False
+
+        for match in line_re.finditer(text):
+            line = match.group()
+            # print line
+            # print code, yml, shs
+
+            # First part - if output starts from '$ ' then it's BASH session
+            # - We must only check that we're not inside of YAML
+            # code can't start with '$ '
+            # if output (not inside YAML) starts with '$ ' - it's not our problem
+            # Also, we can match multiline commands only if line ends with '\'
+            check_shs = (line.startswith('$ ') and not yml) or shs
+            if check_shs:
+                curshs += line
+                if line.endswith('\\'):
+                    shs = True
+                    continue
+                for item in shslexer.get_tokens_unprocessed(curshs):
+                    yield item
+                curshs = ''
+                shs = False
+                continue
+
+            # Second part - check for YAML
+            # 1) It's begin, means (yml == False) and line.strip() == '---'
+            # 2) It's middle. (yml == True) and line.strip() not in ('---', '...')
+            # 3) It's end - then (yml == False) and line.strip() == '...']
+            check_yml_begin  = (yml == False and line.strip()     in (yml_beg, ))
+            # check_yml_middle = (yml == True  and line.strip() not in (yml_beg, yml_end))
+            check_yml_end    = (yml == True  and line.strip() == yml_end and ymlcnt == 0)
+            if (check_yml_begin or yml):
+                # print check_yml_begin, check_yml_middle, check_yml_end
+                # Flush previous code buffers
+                if (yml is True and line.strip() == yml_beg):
+                    ymlcnt += 1
+                if (not check_yml_end and line.strip() == yml_end):
+                    ymlcnt += 1
+                if check_yml_begin and curcode:
+                    for item in do_insertions(insertions, lualexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                    code = False
+                    curcode = ''
+                    insertions = []
+                curyml += line
+                # We finished reading YAML output, so push it to user
+                if check_yml_end:
+                    for item in ymllexer.get_tokens_unprocessed(curyml):
+                        yield item
+                    curyml = ''
+                yml = False if check_yml_end else True
+                # print 'yaml gotcha %d' % yml
+                continue
+
+            # Third part - check for Tarantool's Lua
+            # It's combination of:
+            # prompt: tarantool> or localhost> or localhost:{port}>
+            # lua: body after prompt + space
+            prompt_pos_flexible = find_prompt(line)
+            prompt_pos_strict   = prompt_pos_flexible if not code else None
+            if prompt_pos_strict:
+                prompt_len = prompt_pos_strict + 2
+
+            check_code_begin = bool(prompt_pos_strict)
+            check_code_middle = code and line.startswith(' ' * (prompt_len - 2) + '> ')
+            check_code_flexible = False
+            # e.g. we have two 'tarantool> ' in a row - code is True and
+            # check_code_middle is False then we have to do something about it,
+            # otherwise it will be like Generic.Output
+            if code and check_code_middle is False and bool(prompt_pos_flexible):
+                prompt_len = prompt_pos_flexible + 2
+                check_code_flexible = True
+            if (check_code_begin or check_code_middle or check_code_flexible):
+                code = True
+                insertions.append((len(curcode), [(0, Generic.Prompt, line[:prompt_len])]))
+                curcode += line[prompt_len:]
+                continue
+
+            # If it's not something before - then we must check for code
+            # and push that line as 'Generic.Output'
+            if curcode:
+                for item in do_insertions(insertions, lualexer.get_tokens_unprocessed(curcode)):
+                    yield item
+                code = False
+                curcode = ''
+                insertions = []
+            yield match.start(), Generic.Output, line
+
+        if curcode:
+            for item in do_insertions(insertions, lualexer.get_tokens_unprocessed(curcode)):
+                yield item
+        if curyml:
+            for item in ymllexer.get_tokens_unprocessed(curyml):
+                yield item
+        if curshs:
+            for item in shslexer.get_tokens_unprocessed(curshs):
+                yield item
+
+def setup(app):
+    app.add_lexer("tarantoolsession", TarantoolSessionLexer)