In Sphinx, can I register a bunch of keywords that should always be translated into links?

Question

My doc strings have references to other python classes that I've defined. Every time Sphinx encounters one of these classes, I want it to insert a link to the documentation for that other class. Is this possible in Sphinx?

Specifically, I have a doc string like:

'''This class contains a bunch of Foo objects'''

I could write:

'''This class contains a bunch of :class:`~foo.Foo` objects'''

but I would prefer that Sphinx finds all text matching Foo and makes it seem as though I had typed :class:~foo.Foo

Answer 1

You can use macros.

In my project, I have a header file that contains all "important" classes and global functions and their abbreviation. Two example lines:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`

In my rst files, I include this header file. Then I can use the macros in any rst file:

.. include:: defs.hrst

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not.

(You can include docstrings from Python source files as well, using the autogen extension. Macros in those will be replaced as well.)

About your example: I would add Foo to the header file and write the docstring this way:

'''This class contains a bunch of |Foo| objects'''

Answer 2

Sphinx has a huge number of interpreted text roles for this.

http://sphinx.pocoo.org/markup/inline.html#cross-referencing-python-objects

I want to enter Foo and have Sphinx interpret it as though I had written :class:~foo.Foo

That sounds impractical. It seems like it would paralyze RST trying parse your text. Looking for interpreted text and the few quoting rules that RST supports (*_|`) is about the limit that's practical.

What you're asking for might lead to RST taking all day to check each instance Foo in every possible context and reason out whether you wanted a link or not. You'd want this only in otherwise-undecorated instances of Foo; trivial search and replace wouldn't work.

You can mess with docstring pre-processing.

http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing

This may allow you to try a global search-and-replace strategy on your docstring text.