Как настроить язык кодовых блоков Sphinx? - PullRequest
Новая
       18

Как настроить язык кодовых блоков Sphinx?

1 голос
/ 29 мая 2020

Рассмотрим ситуацию ниже: 

.. code-block:: my_lang

    ...

Если я хочу сделать my_lang чем-то вроде Python, как я могу это сделать?

1 Ответ

1 голос
/ 29 мая 2020

Сначала вам нужно создать сценарий (_ext/mylanglexer.py), а затем добавить extensions в conf.py

( _ext - это соглашение но не обязательно. )

_ext / mylanglexer.py 

# _ext/mylanglexer.py

from pygments.lexers import get_lexer_by_name  # refer LEXERS
from pygments.lexers._mapping import LEXERS
from pygments.lexers.python import PythonLexer


def setup(app):
    # choose one, both ok
    app.add_lexer('my_lang', get_lexer_by_name('py'))
    # app.add_lexer('my_lang', PythonLexer)

conf.py 

# conf.py

extensions = [
    ...
    '_ext.mylanglexer',  # types.ModuleType, they are likely the_module = __import__('sphinx.ext.autodoc')
]

иногда учебник скажите, что вам лучше добавить sys.path.append(os.path.abspath("./_ext")), затем extensions = ['mylanglexer']

В любом случае, если вы знаете, что это модуль, все расширения должны быть import ..., поэтому, если ваш модуль не по умолчанию путь, конечно, вы должны добавить.

Теперь все работает!

Как это работает

см. pygements.lexers.__init__.py

# pygements.lexers.__init__.py

def get_lexer_by_name(_alias, **options):
    ...

    # lookup builtin lexers
    for module_name, name, aliases, _, _ in LEXERS.values():  # <-- Be focus on this line.
        if _alias.lower() in aliases:
            return _lexer_cache[name](**options)  # The class object (module_name+key_name), for example: pygments.lexers.python.PythonLexer(**options)
    # continue with lexers from setuptools entrypoints
    for cls in find_plugin_lexers():

        ...
        return cls(**options)

    raise ClassNotFound('no lexer for alias %r found' % _alias)

В котором LEXERS - это что-то вроде следующего. 

# pygments.lexers._mapping.py

LEXERS = {
    # key_name: module_name, name, aliases: Tuple[str], _, _
    ...
    'ObjectiveCLexer': ('pygments.lexers.objective', 'Objective-C', ('objective-c', 'objectivec', 'obj-c', 'objc'), ('*.m', '*.h'), ('text/x-objective-c',)),
    'ObjectiveCppLexer': ('pygments.lexers.objective', 'Objective-C++', ('objective-c++', 'objectivec++', 'obj-c++', 'objc++'), ('*.mm', '*.hh'), ('text/x-objective-c++',)),
    'ObjectiveJLexer': ('pygments.lexers.javascript', 'Objective-J', ('objective-j', 'objectivej', 'obj-j', 'objj'), ('*.j',), ('text/x-objective-j',)),
    'OcamlLexer': ('pygments.lexers.ml', 'OCaml', ('ocaml',), ('*.ml', '*.mli', '*.mll', '*.mly'), ('text/x-ocaml',)),
    'OctaveLexer': ('pygments.lexers.matlab', 'Octave', ('octave',), ('*.m',), ('text/octave',)),
    'JsonLexer': ('pygments.lexers.data', 'JSON', ('json',), ('*.json', 'Pipfile.lock'), ('application/json',)),
    'PythonLexer': ('pygments.lexers.python', 'Python', ('python', 'py', 'sage', 'python3', 'py3'), ('*.py', '*.pyw', '*.jy', '*.sage', '*.sc', 'SConstruct', 'SConscript', '*.bzl', 'BUCK', 'BUILD', 'BUILD.bazel', 'WORKSPACE', '*.tac'), ('text/x-python', 'application/x-python', 'text/x-python3', 'application/x-python3')),
    ...
}

Вот вы знаете, ваш _alias в aliases, тогда будет работать!

Как я могу настроить мой стиль?

вы можете скопировать и немного изменить лексер, например, ObjectiveCLexer, JsonLexer ...

наконец app.add_lexer('my_lang', YourLexer) вот такая проблема.

...