Articles of python sphinx

¿Cómo documentar una constante de módulo en Python?

Tengo un módulo, errors.py en el que se definen varias constantes globales (nota: entiendo que Python no tiene constantes, pero las he definido por convención utilizando MAYÚSCULAS). “””Indicates some unknown error.””” API_ERROR = 1 “””Indicates that the request was bad in some way.””” BAD_REQUEST = 2 “””Indicates that the request is missing required parameters.””” MISSING_PARAMS […]

¿Cómo escribir correctamente las referencias cruzadas a la documentación externa con intersphinx?

Estoy tratando de agregar referencias cruzadas a la API externa en mi documentación, pero me enfrento a tres comportamientos diferentes. Estoy usando sphinx (1.3.1) con Python (2.7.3) y mi asignación intersphinx está configurada como: { ‘python’: (‘https://docs.python.org/2.7’, None), ‘numpy’: (‘http://docs.scipy.org/doc/numpy/’, None), ‘cv2’ : (‘http://docs.opencv.org/2.4/’, None), ‘h5py’ : (‘http://docs.h5py.org/en/latest/’, None) } No tengo problemas para escribir […]

Parsing reStructuredText en HTML

Estoy creando un marco en el que permito a los desarrolladores describir su paquete utilizando reStructuredText. Quiero analizar ese texto reStructured en HTML para poder mostrarlo en una GUI. Estoy familiarizado con la excelente Esfinge, pero nunca he analizado el texto edStructured. Imaginé algo así como una función que toma una cadena de reStructuredText, y […]

¿Cómo omito los valores de las variables en Sphinx?

Tengo algunas variables de nivel de módulo que tienen valores largos y poco interesantes que me gustaría excluir de la documentación generada automáticamente. ¿Hay alguna forma de hacer esto? Por ejemplo, en mi fuente de Python tengo algo como #:This is a variable with a log value. long_variable = “Some really long value that is […]

Cómo forzar a Sphinx a usar el intérprete de Python 3.x

Intento crear documentación para un proyecto escrito con Python 3.x. Sphinx es la herramienta que quiero usar y, según el sitio oficial , su última versión 1.1.2 es compatible con Python 3.1+ . Mi sistema operativo es Archlinux, una distribución de Linux que utiliza Python 3.2+ como paquete predeterminado de Python. La instalación y configuración […]

Cómo agregar ancla en elemento de lista

Tengo una lista en mi primer archivo que se ve así: – Item 1 – Item 2 – Item 3 Hace algo como lo siguiente (que es exactamente lo que quiero): Objeto 1 Artículo 2 Artículo 3 Me gustaría crear enlaces para cada elemento, así que hice .. _item-1: – Item 1 .. _item-1: – […]

¿Cómo haría una referencia cruzada de una función generada por autodoc en Sphinx?

Estoy usando la función autodoc Sphinx para generar documentación basada en las cadenas de documentación de mi biblioteca de Python. La syntax para las referencias cruzadas se encuentra aquí. Una etiqueta debe preceder a la sección para permitir que esa sección sea referenciada desde otras áreas de la documentación. Lo que tengo es un archivo […]

¿Documentar con métodos Python de Sphinx que tienen parámetros predeterminados con objetos centinela?

Si desea poder permitir que las personas llamen a algunos métodos utilizando None , debe utilizar un objeto centinela cuando defina el método. _sentinel = object() def foo(param1=_sentinel): … Esto le permitiría llamar a foo(param1=None) y ser capaz de marcar la diferencia entre una llamada como foo() . El problema es que cuando Sphinx documenta […]

Cómo documentar el código de Python con doxygen

Me gusta doxygen para crear documentación de código C o PHP. Tengo un proyecto próximo de Python y creo que recuerdo que Python no tiene /* .. */ comments, y también tiene su propia función de autodocumentación, que parece ser la forma en que se documentan los pitones. Ya que estoy familiarizado con doxygen, ¿cómo […]

Generar automáticamente salida doctest con extensión Sphinx

Creo que me estoy perdiendo algo acerca de la extensión de la esfinge para doctest. El ejemplo típico en la documentación es: .. doctest:: >>> print 1 1 ¿No hay una manera de permitir que la esfinge genere la salida (aquí: 1 ) automáticamente? Por lo que he entendido, es posible ejecutar: $ make doctest […]