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?

score 33 · Answer 1 · answered Aug 04 '15 at 23:07

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

This is very sad but seems to be the only viable solution :(. It's really unfortunate that Sphinx doesn't support such a seemingly simple, often needed feature — Michael Panchenko, Apr 02 '23 at 12:33

score 11 · Answer 2 · answered Feb 19 '17 at 22:59

11

In the current version of Sphinx you can just put

.. toctree::

   Title <http://LINK>

and it will work.

answered Feb 19 '17 at 22:59

niedakh

2,819
2
20
19

3

This does not currently work with relative links: https://github.com/sphinx-doc/sphinx/issues/701 – mhsmith Jun 20 '17 at 23:14

score 5 · Answer 3 · answered Jan 07 '16 at 23:31

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.

You can also use this, but with the `html_extra_path` setting in conf.py to have sphinx copy over files for you. — Ash Berlin-Taylor, Oct 03 '17 at 11:32

Stefan · Answer 4 · 2015-01-21T11:02:09.827

-7

The following syntax works for me:

`Page Title <../relative/path.html>`

edited Jan 21 '15 at 11:02

answered Jan 20 '15 at 08:53

Stefan

1,131
2
12
30

Hi, I've checked but this didn't work insode ..toctree:: directive. I've got this error: WARNING: toctree contains reference to nonexisting document u'`Page Title <../relative/path.html>`' – Ido Ran Jan 25 '15 at 15:07
1

I only used that within a normal section, not in a toctree directive. – Stefan Jan 25 '15 at 19:46

External Relative Link in Sphinx toctree directive

4 Answers4

Linked