В данной главе приведены известные проблемы, с которыми я столкнулся за время эксплуатации Sphinx.
Кириллические элементы алфавитного указателя не сортируются по алфавиту и попадают в раздел символы
. Решение проблемы пока мною не найдено.
Подписи к таблицам и рисункам в HTML отображаются без названия категории «Таблица» или «Рисунок», но в LaTeX-документах к подписям автоматически добавляется и категория с номером. Нумерация также осуществляется автоматически.
При создании перекрестных ссылок на иллюстрации и таблицы ссылка принимает название этих объектов, что не очень удобно если названия длинные. Обычно в документации принято делать ссылки в формате «см. Рисунок N».
В LaTeX-документах ссылки на рисунки и таблицы также преобразуются в названия, а не в категории.
Способ обхода этой проблемы описан здесь. У меня не было времени его протестировать. Буду благодарен, если кто-нибудь поделится своим опытом на этот счёт.
Столкнулся с проблемой масштабирования изображений в LaTeX. При использовании директивы .. image::
с параметрами :height:
или :width
масштабирование изображений в LaTeX не происходило. При использовании директивы .. figure::
с параметром :scale:
все работает как надо, изображения масштабируются.
При сборке PDF используется генерация в LaTeX. Стандартные настройки шаблона LaTeX, используемого Read the Docs, не поддерживают кириллицу. Чтобы включить поддержку кириллицы, необходимо поправить преамбулу LaTeX в файле настроек Sphinx-проекта conf.py
. Подробнее смотрите пример ltx-label
.
Многие проблемы с отображением тех или иных фрагментов текста в ePub связаны непосредственно с просмотрщиками электронных книг. Например, плагин к браузеру Firefox для просмотра ePub отлично отображает все элементы. На Android в программе CoolReader некорректно отображаются листинги. В программе FBreader листинги отображаются хорошо, а вот таблицы сбиваются.
У меня возникли проблемы с отображением формул на Read The Docs при использовании расширения sphinx.ext.mathjax
, пересобрав документацию с расширением sphinx.ext.pngmath
все стало в порядке. Подробнее смотрите раздел ext-math-label
.
Также проблема с отображением формул может появиться при использовании символов греческого алфавита (α, β и т.д.) внутри формулы. Так как Sphinx использует для набора синтаксис LaTeX, то набирать данные символы надо следующим образом: \alpha
, \lambda
и т.д. (смотрите Перечень команд LaTeX для набора греческих букв). :
.. math::
\alpha_t(i) = P(O_1, O_2, … O_t, q_t = S_i \lambda)
Результат:
αt(i) = P(O1, O2, …Ot, qt = Siλ)