External Relative Link in Sphinx toctree directive

Question

I'm using Sphinx to build my documentation. I'm using other tool for API reference. I have my docs in a directory and the API reference in directory name api inside of it.

I want to have a link from the documentation to the API reference. I'm able to add a link to my toctree link so:

.. toctree::
   :maxdepth: 1

   starting
   glossary
   main-use-case-flow
   API Reference <http://www.example.com/lib/ios/0.1.0/api/>

The problem is I don't want to put a full path, I want to put just the relative path api/

How can I put a link to external resource using relative path and not absolute path?

Answer 1

I found one of the hackiest ways possible to do this. Basically Sphinx allows either a path to a document or an absolute path that requires http://. It turns out all they do to validate your link is look for literally http://.

*WARNING: toctree contains reference to nonexisting document u'downloads'*
Downloads <../downloads>

But if you do:

Downloads <../downloads#http://>

No warning! This does mean however that when the user clicks on your link, it inserts the http:// fragment or named anchor to your page link. If this is not a valid named anchor in your html, it will do nothing to your page (unless your page has some javascript that does something with the named anchor).