Apr 8, 2015

Sphinx, autodoc, python docstring, math mode, issues

Found an issue. For math mode to work in autodoc sphinx documentation build, the docstring in the to-be-documented python module has to be in one paragraph.



For example:
def function_to_be_documented():
'''return the initial condition of body angular velocity required to generate a uniform precession top. Calculation base on the parameters and the setup of the top. The formula is in Goldstein's book. The formula has a singular point at :math:`\\theta` = 90 degree, but a unique way is developed to deal with this. So the program will work at any angle.'''

the \\theta will be printed correctly. But with the following the \\theta will not be printed.
def function_to_be_documented():
'''return the initial condition of body angular velocity required to generate a uniform precession top.
   
Calculation base on the parameters and the setup of the top. The formula is in Goldstein's book. The formula has a singular point at :math:`\\theta` = 90 degree, but a unique way is developed to deal with this. So the program will work at any angle.'''


No comments: