Python Sphinx referencing long names

问题:

I'm working on documentation for my Python module (using Sphinx and reST), and I'm finding that when cross-referencing other Python objects (modules, classes, functions, etc) the full object name ends up being incredibly long. Often it is longer than 80 characters, which I would like to avoid at all costs.

Here is an example:

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName`

    '''

The issue is that when creating the documentation for the ReallyLongExampleClassName class, I generated it for the full path name module1.module2.module3.module4.module5.ReallyLongExampleClassaName.

I'm wondering if there is any way to solve this? I have tried the following methods, with no success:

1) Adding a line break in the middle of the module name. Example:

:class:`module1.module2.module3.module4.
module5.ReallyLongExampleClassName`

2) Referencing the class name in a different (but still Python importable) way. Example:

:class:`module1.module2.ReallyLongClassName`

I believe that since the documentation for ReallyLongClassName is tied to the full path names that Sphinx cannot correlate the shortened version with the fully named version.

Any help will be greatly appreciated.

Edit 04/05/2012:

As per the answer/suggestion of j13r (see below) I tried the following:

:class:`module1.module2.module3.module4.module5\
ReallyLongExampleClassName`

And this worked successfully. The only caveat to get this to work, is that the second line must not have spaces before it (which is quite frustrating when using this in a docstring). Thus to make my original example work it would look like:

def exampleFunction():
    '''Here is an example docstring referencing another
    :class:`module1.module2.module3.module4.module5.\
ReallyLongExampleClassName`

    '''

Nice, and ugly. If you were to put spaces before "ReallyLongExampleClassName" to indent it to the same level as the line above it the output would include the spaces and thus Sphinx would try to reference something like "module1.module2.module3.module4.module5. ReallyLongExampleClassName."

I should also note that I tried two other variations of this, which did NOT work:

    # Note: Trying to put a space before the '\'
    :class:`module1.module2.module3.module4.module5. \
ReallyLongExampleClassName`

    # Note: Trying to leave out the '\'
    :class:`module1.module2.module3.module4.module5.
ReallyLongExampleClassName`

I was looking for a solution that didn't involve destroying the formatting of the docstring, but I suppose it will do...I think I actually prefer a line that goes past 80 characters to this.

Thanks to j13r for the answer!

回答1:

According to the sphinx documentation (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) you could use a dot before your target class:

:class:`.ReallyLongExampleClassName`

or

:class:`.module5.ReallyLongExampleClassName`

and let sphinx search for the class:

... if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:.TarFile.close references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

回答2:

You can use ~ as prefix, it does exactly what you want.

http://sphinx-doc.org/markup/inline.html#xref-syntax

回答3:

Wild stab in the dark. Perhaps this works:

:class:`module1.module2.module3.module4.\
module5.ReallyLongExampleClassName`

It would be valid Python

import scipy.\
stats

回答4:

Another strategy is to use reST Substitutions. This will let you save more space in the text by calling the :class: cross-reference later on:

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    .. |ReallyLongExampleClassName| replace:: 
                                    :class:`.ReallyLongExampleClassName`

    '''

If you're referring to the same class in many of your files, you could instead put the substitution in your Sphinx conf.py file, using the rst_epilog setting. From the Sphinx documentation:

rst_epilog

A string of reStructuredText that will be included at the end of every source file that is read. This is the right place to add substitutions that should be available in every file. An example:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

New in version 0.6.

Then your docstring would just be:

def exampleFunction():
    '''Here is an example docstring referencing another
    |ReallyLongExampleClassName|

    '''