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).

Answer 2

In the current version of Sphinx you can just put

.. toctree::

   Title <http://LINK>

and it will work.

Answer 3

I encountered this problem when I tried to add links to (generated) javadocs to my toctree.

My solution was to create a phony index.rst in the appropriate location within my source tree to satisfy the requirements of toctree. I discovered the phony index.rst file must contain a title, so my file looked like this:

=======================
Java API (All Packages)
=======================

When you run make, this file gets copied into your build directory, _build/html (or whatever).

And then simply replace it with the real file after reStructuredText processing.