Python Sphinx refers to long names

Question

I am working on documentation for my Python module (using Sphinx and reST), and I find that when cross-referencing other Python objects (modules, classes, functions, etc.), the full name of the object ends up incredibly long. This is often 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 problem is that when I created the documentation for the ReallyLongExampleClassName class , I generated it for the fully qualified path name module1.module2.module3.module4.module5.ReallyLongExampleClassaName.

I am wondering if there is a way to solve this? I tried the following methods, without success:

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

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

2) A reference to the class name in another (but still Python-imported) way. Example:

 :class:`module1.module2.ReallyLongClassName` 

I believe that since the documentation for ReallyLongClassName is tied to the full path name, Sphinx cannot match the shortened version to the fully named version.

Any help would be greatly appreciated.

Edit 05/05/2012 :

In accordance with j13r's answer / suggestion (see below) I tried the following:

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

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

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

Nice and ugly. If you had to put spaces in front of "ReallyLongExampleClassName" in order to fall back at the same level as the line above it, the output would include spaces, and thus Sphinx will try to reference something like "module1.module2.module3.module4 .module5 ". ReallyLongExampleClassName. "

I should also note that I tried two other variants of this that 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 did not involve destroying the docstring formatting, but I suppose it will be ... I think I prefer a line that exceeds 80 characters.

Thanks j13r for the answer!

Answer 1

According to sphinx documentation ( https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects ) you can use the dot in front of the target class:

 :class:'.ReallyLongExampleClassName' 

or

 :class:'.module5.ReallyLongExampleClassName' 

and let the sphinx look for a class:

... if a dot is put before the name and no exact match is found, the target is taken as a suffix and all objects with this suffix are searched. For example: py: meth: .TarFile.close refers to the tarfile.TarFile.close () function, even if the current module is not a tarfile. Since this can become ambiguous, if there is more than one possible match, you will receive a warning from the Sphinx.

Answer 2

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

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

Answer 3

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

 def exampleFunction(): '''Here is an example docstring referencing another |ReallyLongExampleClassName| .. |ReallyLongExampleClassName| replace:: :class:`.ReallyLongExampleClassName` ''' 

If you reference the same class in many of your files, you can instead replace it in the conf.py Sphinx file using rst_epilog . From the Sphinx documentation:

rst_epilog

The string reStructuredText to be included at the end of each source file that is being read. This is a good place to add replacements that should be available in every file. Example:

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

New in version 0.6.

Then your docstring will be as follows:

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

Answer 4

Wild blow in the dark. Maybe this works:

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

It will be valid Python

 import scipy.\ stats