autodoc: Extract docstring, leave the signature up to me

[shimizukawa]

I keep running into this problem. This seems too hard.

I have a bunch of objects in Python from which I want to extract the docstring. I'm using ::autodata::

By default, I am seeing something like this:

my_module.SETTING = <property object at 0x193d368>
   <docstring...>

What I would prefer is just

SETTING
   <docstring...>

Even implementing the process-signature event, this seems not properly possible, since both return values are only appended to the basename.

Interestingly, when autodoc-process-signature does return a value in either field of the tuple (unfortunately, not an empty string), the string that is used for the base DOES change. So, with::

def process_signature(*a, **kw):
    return ('foo', '')

the output is:

ASSETS_ROOTfoo

as opposed to:

my_module.ASSETS_ROOTfoo

which seems like it might simply be an unintended effect.

I would love to see some way to fetch docstrings and insert them into the documentation without the constraints of autodoc.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/963
• Originally reported by: Michael Elsdörfer
• Originally created at: 2012-07-08T17:58:53.388

[shimizukawa]

From Michael Elsdörfer on 2012-07-08 16:36:51+00:00

FWIW, after spending some time reading the code, I now understand that the thing that I return from my autodoc-process-signature handler is inserted verbatim into a :py:data: directive; as a result of which, it will no longer be associated with the property in the index, if I put custom stuff in there.

What is happening is quite opaque if one doesn't know what is going on behind the scenes.

I have no solved this for me by implementing a custom Documenter class, though I still would like to see this improved. In particular, I'm still unable to get rid of the module prefix. That is, what is generated is:

{{{
my_module.SETTING
}}}

and what I would like is:

{{{
SETTING
}}}

[shimizukawa]

From Jon Waltman on 2012-09-21 00:55:04+00:00

The configuration variable [[http://sphinx.pocoo.org/config.html?highlight=add_module_names#confval-add_module_names|add_module_names]] can be used to control whether or not the current module name is appended to each description.

You can try it out by adding this in your conf.py:

{{{
add_module_names = False
}}}

Does this do what you want?

[shimizukawa]

From Johannes Dewender on 2013-01-21 16:46:31+00:00

I am having a similar issue.

I also use autodata:: for module constants and I want the docstring, but not the value.
The value depends on the platform.
Having the module as a prefix is fine.

Code is like this:

:::python
#: The default device to use for :func:read
DEFAULT_DEVICE = _get_default_device()

With autodata:: DEFAULT_DEVICE I get:

mymodule.DEFAULT_DEVICE = u'/dev/cdrom'
    The default device to use for read()

I cannote use autodoc-process-signature because that does not apply here (signature and return_annotation are both None).

I am using my own DataDocumentor now that uses a :novalue: option (also useful for AttributeDocumentor)

I can open a pull-request, if anybody is interested.

[shimizukawa]

From Johannes Dewender on 2013-01-22 17:41:15+00:00

I did open a pull-request: pull request #109

[maxking]

FWIW, I had a need for a similar feature too. Although, for now, I was able to remove the values by by using a custom css:

.property {
  display: None
}

I know, not the most ideal thing, but gets my job done.

[tk0miya]

Since 3.4.0, autodoc and autoattribute support :no-value: option to suppress the right-hand value of the variables. So you can suppress an arbitrary variable manually. Of course, you can suppress right-hand values in the whole of your document via autodoc_default_options.

In addition to this, I posted #8596 to suppress it via metadata in the docstring.

Hence, I consider this issue has been resolved finally. Thanks.