Short name for members in documentation

[Rahul Surana]

Hi,

Is there an option or config variable that can be set/added to sphinx to avoid showing fully qualified name of a member?

Consider below sample page:

---------------------------------------------------------------------------------------------------
python.sphinx.documentation.example.test.module_members.fully_qualified_name

<<<docstring of the module>>>

class python.sphinx.documentation.example.test.module_members.fully_qualified_name.TestClass():

    Bases: object

    <<<docstring of class>>

def python.sphinx.documentation.example.test.module_members.fully_qualified_name.testfunction(name1=True, name2=False, name3=None,......):

     <<<docstring of function>>>

........

---------------------------------------------------------------------------------------------------

Given the user has navigated to "python.sphinx.documentation.example" page for documentation, prefixing the modname to member name

or displaying the fully qualified name looks a bit overkill in certain cases.

Consider the "testfunction" function above, on the first look it is harder to identify where the arguments for the function start.

I went through the source code and identified that updating below did the trick for me:

• For displaying shorter names:
  

Change in sphinx.domains.python.PyObject.add_target_and_index:339

signode['names'].append(fullname)    => signode['names'].append(name_cls[0])

signode['ids'].append(fullname)      => signode['ids'].append(name_cls[0])

• For using shorter names in references:
  

Change in sphinx.writers.html.HTMLWriter:355

format = u'<a class="headerlink" href="#%s" title="%s">%s</a>'
                                                                    => refname = node['ids'][0]
                                                                    => refname = refname,rsplit('.', 1)[1] if '.' in refname else refname
.body.append(format % (node['ids'][0], title, self.permalink_text)) => .body.append(format % (node['ids'][0], title, self.permalink_text))

I could use the below changes in my local installation but i don't want to patch sphinx on every release. [Note: Since self.env.domaindata['py']['objects'] mapping would use fullname for key, multiple members with same name across packages wouldn't mess up the doc]

Instead it would be much appreciated if sphinx supported this change.

Thanks in advance!

[Jan Ulrich Hasecke]

In a reference you can write:

py:meth:`~tarfile.TarFile.close`

to get "close()" only.

juh

On 05.09.2018 09:35, Rahul Surana wrote:
> Hi,
>
> Is there an option or config variable that can be set/added to sphinx to
> avoid showing fully qualified name of a member?
> Consider below sample page:
>
> ---------------------------------------------------------------------------------------------------

> */python.sphinx.documentation.example.test.module_members.fully_qualified_name/*

>
> <<<docstring of the module>>>
>
> class

> /python.sphinx.documentation.example.test.module_members.fully_qualified_name.TestClass/():

>     Bases: object
>
>     <<<docstring of class>>
>
> def

> /python.sphinx.documentation.example.test.module_members.fully_qualified_name.testfunction/(name1=True,

> name2=False, name3=None,......):
>      <<<docstring of function>>>
>
> ........
> ---------------------------------------------------------------------------------------------------
>
> Given the user has navigated to "python.sphinx.documentation.example"
> page for documentation, prefixing the modname to member name
> or displaying the fully qualified name looks a bit overkill in certain
> cases.
>

> Consider the "*testfunction*" function above, on the first look it is

> harder to identify where the arguments for the function start.
>
>
>
> I went through the source code and identified that updating below did
> the trick for me:
>

> * For displaying shorter names:

>
>
> Change in sphinx.domains.python.PyObject.add_target_and_index:339
>
> |
> signode['names'].append(fullname)   =>signode['names'].append(name_cls[0])
>
> signode['ids'].append(fullname)     =>signode['ids'].append(name_cls[0])
> |
>
>

> * For using shorter names in references:
>
>
> Change in sphinx.writers.html.HTMLWriter:355
>
> |
> format =u'<a class="headerlink" href="#%s" title="%s">%s</a>'

>                                                                    
> =>refname =node['ids'][0]
>                                                                    
> =>refname =refname,rsplit('.',1)[1]if'.'inrefname elserefname
> .body.append(format
> %(node['ids'][0],title,self.permalink_text))=>.body.append(format
> %(node['ids'][0],title,self.permalink_text))
> |
>
>
> I could use the below changes in my local installation but i don't want
> to patch sphinx on every release. [Note:
> Since self.env.domaindata['py']['objects'] mapping would use fullname
> for key, multiple members with same name across packages wouldn't mess
> up the doc]
> Instead it would be much appreciated if sphinx supported this change.
>
>
> Thanks in advance!
>

> --
> You received this message because you are subscribed to the Google
> Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to sphinx-users...@googlegroups.com
> <mailto:sphinx-users...@googlegroups.com>.
> To post to this group, send email to sphinx...@googlegroups.com
> <mailto:sphinx...@googlegroups.com>.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.

[Rahul Surana]

Thanks for the reply Jan!

The py:meth:`~tarfile.TarFile.close` works fine to shorten the reference.

I needed a way to have shortened name for Tarfile class in tarfile module documentation.

FTR, i've no custom rsts and all the documentation is generated be importing & parsing the docsting.

Sphinx by default uses fully qualified name for module members and just the name for class members.

In above example, as expected one needs to go to tarfile module documentation to view documentation for Tarfile class.

It seems a bit of overkill to have fully qualified name (class tarfile.Tarfile) instead of just (class Tarfile).

Also the url looks kinds lengthy. Ex: https://<doc_site>/tarfile.html#tarfile.TarFile.close.
Ideally, i would expect this to be just - https://<doc_site>/tarfile.html#TarFile.close.

This may seem innocuous with the above example, but with depth of sub-modules more than 5 or 7 and larger names, this would be quite lengthy.

For the time being, i've overridden some of the sphinx writer (HTMLWriter) methods to use simple name (class Tarfile) and shortened references across the documentation.

This would be good feature to have in sphinx.

> <mailto:sphinx-users+unsub...@googlegroups.com>.