Parameter types: shortening with tilde...

[Infinity77]

Hi All,

I am trying to document parameter types for the Phoenix project (next generation of wxPython). I have the following issue: if I document a parameter in this way:

      :param `col`: The column I am interested in

      :type `col`: dataview.DataViewColumn

Then I get this output from Sphinx:

Parameters:	col (dataview.DataViewColumn) – The column I am interested in

I am trying to remove the module name in front of DataViewColumn, so I naively tried this:

      :param `col`: The column I am interested in

      :type `col`: `~dataview.DataViewColumn`

With the tilde in fron of the module name. But in this case, no hyperlink is generated by Sphinx for the parameter type (i.e., it's only italicized).

Am I missing something?

Thank you in advance for any suggestion.

Andrea.

[Jonathan Waltman]

The tilde prevents it from being a link:
http://sphinx-doc.org/markup/inline.html?highlight=semantic#cross-referencing-syntax

You can prevent the module name via the configuration value add_module_names
http://sphinx-doc.org/config.html?highlight=add_mod#confval-add_module_names

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To post to this group, send email to sphinx...@googlegroups.com.
> To unsubscribe from this group, send email to sphinx-users...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users?hl=en.
>
>

--
Jonathan Waltman

[Infinity77]

Hi,

On Wednesday, December 5, 2012 5:18:20 PM UTC+1, Jonathan Waltman wrote:

The tilde prevents it from being a link:
http://sphinx-doc.org/markup/inline.html?highlight=semantic#cross-referencing-syntax

No, see the following:

If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

 

You can prevent the module name via the configuration value add_module_names
http://sphinx-doc.org/config.html?highlight=add_mod#confval-add_module_names

I already set add_module_names to False in the conf.py file. 

[Jonathan Waltman]

On Wed, Dec 5, 2012 at 2:39 PM, Infinity77 <andrea...@gmail.com> wrote:
> Hi,
>
>
> On Wednesday, December 5, 2012 5:18:20 PM UTC+1, Jonathan Waltman wrote:
>>
>> The tilde prevents it from being a link:
>>
>> http://sphinx-doc.org/markup/inline.html?highlight=semantic#cross-referencing-syntax
>>
>
> No, see the following:
>
> If you prefix the content with ~, the link text will only be the last
> component of the target. For example, :py:meth:`~Queue.Queue.get` will refer
> to Queue.Queue.get but only display get as the link text.

By tilde, I of course meant an exclamation point... :-)

>> > I am trying to document parameter types for the Phoenix project (next
>> > generation of wxPython). I have the following issue: if I document a
>> > parameter in this way:
>> >
>> > :param `col`: The column I am interested in
>> > :type `col`: dataview.DataViewColumn

Is this a typo and you actually have backticks around the
dataview.DataViewColumn? eg

:type `col`: `dataview.DataViewColumn`

>> > I am trying to remove the module name in front of DataViewColumn, so I
>> > naively tried this:
>> >
>> > :param `col`: The column I am interested in
>> > :type `col`: `~dataview.DataViewColumn`
>> >
>> > With the tilde in fron of the module name. But in this case, no hyperlink is generated by Sphinx for the parameter type (i.e., it's only italicized).

Hmm, this appears to be right actually. I don't see why if the above is
working why this one isn't.

Does explicitly using the :class: or :obj: role make any difference?

:obj:`dataview.DataViewColumn`
:obj:`~dataview.DataViewColumn`
:class:`dataview.DataViewColumn`
:class:`~dataview.DataViewColumn`

Is the "currentmodule" what you expect? Does it help changing it?

.. currentmodule:: xxx

This could be an issue with how Sphinx is looking up the object.
It sometimes has issues with documenting C extensions and
packages with unusual imports.


--
Jonathan Waltman