Подсветка кода в Sphinx и Pygments: почему кажется неполной и как выбрать стиль

Разбираем, почему в Sphinx код Python подсвечен частично: роль стиля Pygments, как перечислить доступные стили и выбрать подходящий, чтобы улучшить читаемость.

Подсветка кода в Sphinx, которая не совпадает с тем, что вы видите в редакторе, может удивлять, особенно когда части фрагмента Python остаются неокрашенными. Если ваша документация использует оформление по умолчанию, а вы ожидаете палитру «как в VS Code», корень несоответствия почти всегда в выбранном стиле, а не в ошибке вашей настройки.

Суть проблемы

У вас в Sphinx есть блок кода на Python, и вы замечаете, что подсвечены только отдельные части. Конфигурация использует стиль по умолчанию. Фрагмент выглядит так:

import logging as logsys
logsys.getLogger('mymodule').setLevel(logsys.INFO)

На собранной странице вызовы функций и некоторые имена остаются без подсветки, тогда как ключевые слова и строки могут быть выделены. Если вы рассчитываете на более широкую палитру цветов токенов, как в вашей IDE, это кажется незавершённым.

Что на самом деле происходит

Визуальный результат зависит от активного стиля Pygments. Стиль определяет, какие типы токенов получают цвет, а какие остаются нейтральными. Многие встроенные стили намеренно оставляют места вызова и некоторые имена без оформления. Это дизайнерское решение темы, а не сбой подсветчика. Как отмечено в справочнике по стилям Pygments, в их примерах большинство стилей не раскрашивают функции в местах вызова.

Большинство стилей не раскрашивают функции в местах вызова (Math.fib в тех примерах).

Если «частичная подсветка» выглядит для вас неправильной, вероятнее всего, вам просто нужен другой стиль, который окрашивает больше категорий токенов и лучше соответствует вашим предпочтениям.

Решение

Сначала перечислите, какие стили доступны в вашей среде, чтобы их попробовать. Запустите небольшой помощник:

from pygments.styles import get_all_styles as enumerate_styles
print(list(enumerate_styles()))

Он выведет названия, которые можно подставить в конфигурацию Sphinx. Дальше — обычный перебор: выберите стиль-кандидат из списка, соберите документацию и оцените результат. Если ни один из встроенных вариантов не устраивает, установите плагин, который предоставляет стиль, ближе соответствующий вашим предпочтениям.

Почему это важно

Документация — часть вашего опыта разработчика. Читаемые примеры кода снижают когнитивную нагрузку, ускоряют просмотр и уменьшают вероятность ошибок при копировании. Когда подсветка соответствует тому, как вы мыслите о коде, проще заметить главное в фрагменте — будь то вызовы функций, доступ через пространство имён или уровни логирования. Правильно выбранный стиль — небольшой штрих с высокой отдачей.

Итоги

Если фрагменты Python в Sphinx выглядят «наполовину раскрашенными», это не обязательно баг. Эффект вызван выбранным стилем Pygments, и многие стили по умолчанию намеренно оставляют места вызова и некоторые имена без цвета. Программно перечислите доступные стили, попробуйте несколько и переключитесь на тот, что соответствует вашим визуальным ожиданиям. Если ничего не откликается, поищите внешний плагин со стилем, который лучше вписывается в ваш рабочий процесс.