Question

I am documenting my code using Shinx. In some files I have mathematical formulas and would like to include a reference to them. Being in the very same file this is not a problem. Using :eq:'reference'.

However, how do you cross reference to a formula from a different file? In my case Sphinx is unable to find the reference.

Answer 1

According to the Sphinx docs here, equation cross-referencing only works within the same document at present. I suggest submitting a bug/feature request to get this changed (assuming there isn’t one already).

As a workaround, you can probably use the generic cross referencing syntax by placing a reference label immediately before the equation you want to reference (in the “other” file), like so:

.. _equation_in_other_file:

and then use something like:

:ref:` Link Title <equation_in_other_file>`

in the “current” file to reference it.

(note you need to provide an explicit link title)

It’s not quite as elegant, but it should get the job done.