sphinx: doc reference by using substitution and custome 'doc' inline directive. inspired by https://bitbucket.org/birkenfeld/sphinx/issue/1077

conf.py

############################################
# inline doc directive for substitution
# rst: .. |sub| doc:: docname
# html: <a href="docname.html">sub</a>

from sphinx.util.compat import Directive
from sphinx.roles import XRefRole

class DocDirective(Directive):
    required_arguments = 1

    def run(self):
        docname = self.arguments[0]
        text = self.state.parent['names'][0]
        rawtext = "%s <%s>" % (text, docname)
        return XRefRole(warn_dangling=True)(
            'doc', rawtext, rawtext, self.state.parent.line, self.state)[0]


def setup(app):
    app.add_directive('doc', DocDirective)

index.html

<p>This is link to <a class="reference internal" href="foo.html"><em>The Foo</em></a> by using substitution.</p>

index.txt

This is link to |The Foo| by using substitution.

.. |The Foo| doc:: foo