Математическое выражение в строке документации неправильно отображается Sphinx

Я пытался выяснить, что не так с этим выражением в моей строке документации. Я использую расширение sphinx.ext.mathjax в python sphinx v1.2b. Строка документации:

.. math::

    w_k^* = \min_{w_k} \ell_k(w_k) + \lambda\left(\alpha||w_k||_1 
    + \frac{1}{2}(1-\alpha) ||w_k||^2\right)

Вот что появляется: введите здесь описание изображения

Но он продолжает генерировать это странное предупреждение и вообще не отображает выражение:

WARNING: Block quote ends without a blank line; unexpected unindent.

Как ни странно, если я удаляю символы \alpha, \left, \right, \frac, выражение отображается нормально без предупреждений. Не знаю, почему будет поддерживаться \lambda, а не \alpha.


python-sphinx latex mathjax docstring
person bluecat    schedule 09.05.2013    source источник

Ответы (1)


arrow_upward
15
arrow_downward

Из документации Sphinx:

Имейте в виду, что когда вы добавляете математическую разметку в строки документации Python, читаемые autodoc, вам нужно либо удвоить все обратные косые черты, либо использовать необработанные строки Python (r"raw").

Это необходимо, чтобы команды LaTeX, такие как \alpha, интерпретировались правильно (\a и некоторые другие последовательности имеют специальное значение в строковом литерале).

Это необработанная версия строки документации в вопросе с тройными кавычками, перед которой стоит r:

r"""
.. math::
 
    w_k^* = \min_{w_k} \ell_k(w_k) + \lambda\left(\alpha||w_k||_1 
    + \frac{1}{2}(1-\alpha) ||w_k||^2\right)
"""
person mzjn    schedule 09.05.2013
comment
Спасибо, это действительно была проблема. Должен ли я всегда удваивать все обратные косые черты? Я пытаюсь следовать стандарту numpy doscstring . Но они не используют необработанные строки или двойную обратную косую черту. - person bluecat; 10.05.2013
comment
Не все команды LaTeX конфликтуют со специальными управляющими последовательностями Python. Вы сами отметили, что \lambda сработало. Таким образом, не совсем верно, что вы всегда должны использовать двойную обратную косую черту или использовать необработанные строки (но это кажется хорошей практикой, чтобы уберечь себя от неприятностей). - person mzjn; 10.05.2013
comment
Я думаю, было бы полезно показать исходное уравнение: w_k^* = \min_{w_k} \ell_k(w_k) + \lambda\left(\alpha||w_k||_1 + \frac{1}{2}( 1-\alpha) ||w_k||^2\right), а затем показать, как его нужно изменить, чтобы Autodoc правильно прочитал его внутри строки документации Python. - person benjaminmgross; 15.11.2013
comment
@Factor3: уравнение не нужно изменять. Все, что нужно, это r перед строкой документации (чтобы сделать строку необработанной). - person mzjn; 15.11.2013
comment
@mzjn, спасибо. Итак, чтобы уточнить, функция :math:'\sigma_t \triangleq X + Y', скорее всего, не будет отображаться внутри строки документации Python и должна быть записана как :math:r'\sigma_t \triangleq X + Y', и будет отображаться в строка документации Python правильно? - person benjaminmgross; 19.11.2013
comment
@Factor3: r должен стоять непосредственно перед строковым литералом. Вот пример: stackoverflow.com/a/8386407/407651. - person mzjn; 19.11.2013