Omitir (o formatear) el valor de una variable al documentar con Sphinx

Question

Actualmente estoy documentando un módulo completo con autodoc. Sin embargo, defino varias variables en el nivel de módulo que contienen largas listas o dicts. Se incluyen en la documentación junto con los valores, y los valores no están formateados, por lo que parece un lío de 10 líneas. Lo que quiero es que se incluya el docstring de esas variables, pero que los valores se omitan o al menos tengan un buen formato.

he tratado de excluir la variable de automodule Directiva y añadirlo al igual que:

.. automodule:: foo.bar 
    :members: 
    :exclude-members: longstuff 

    .. py:data:: longstuff 

Esto dio lugar a que sólo el nombre de la variable se incluyó, mientras que tanto la cadena de documentación y el valor de longstuff no eran presente en la documentación.

¿Cómo puedo mantener el docstring y deshacerme del valor (o tener un buen formato) al mismo tiempo? Gracias por adelantado.

Answer 1

No existe una configuración de configuración simple para omitir los valores de las variables de nivel de módulo en la salida. Pero puede hacerlo modificando el método DataDocumenter.add_directive_header() en autodoc.py. La línea fundamental en ese método es

self.add_line(u' :annotation: = ' + objrepr, '<autodoc>') 

donde objrepr es el valor.

El siguiente parche mono añadió a conf.py funciona para mí:

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter 

def add_directive_header(self, sig): 
    ModuleLevelDocumenter.add_directive_header(self, sig) 
    # Rest of original method ignored 

DataDocumenter.add_directive_header = add_directive_header