relative links in toctree

[shimizukawa]

I'd like to use relative URLs in toctrees, but can't figure out how.
It seems right now I have the choice between either internal links (where the target is another document), or an (absolute) URL. The latter is identified by means of a sphinx.util.url_re.

Is there a way to have a toctree entry use a relative link, such that the generated html contains 'href=".../some/path.html"' ?

(If it isn't yet supported, perhaps a new pseudo-schema would work, such as 'relative:.../some/path.html', from which the 'relative:' would then be stripped off during html generation ?)

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/701
• Originally reported by: Anonymous
• Originally created at: 2011-05-22T03:17:53.521

[shimizukawa]

From Anonymous on 2012-04-18 14:10:29+00:00

I would also like to use relative document locations that are not within the directory tree housing conf.py. For instance, see my stack overflow question:

http://stackoverflow.com/questions/10199233/can-sphinx-link-to-documents-that-are-not-located-in-directories-below-the-root

[shimizukawa]

From rdburns on 2012-04-18 14:12:13+00:00

That previous comment was me, forgot to login.

[shimizukawa]

From Mac Ryan on 2012-08-02 10:26:08+00:00

I second this request (just in case the number of people requesting this feature influences the priority queue...). :)

[shimizukawa]

From Dmitriy Kruglov on 2012-09-13 09:35:01+00:00

One more vote to have the feature.

[shimizukawa]

From Marcus Lindblom Sonestedt on 2012-10-17 10:50:22+00:00

We'd like this too! :)

[shimizukawa]

From Gringo Suave on 2012-12-14 03:35:35+00:00

Bitbucket demands I keep my readme in the root, sphinx demands I keep it in ./docs ... what to do? I'd use a filesystem link but project needs to be able to work under Windows and hg doesn't support links there.
I'll have to keep two copies in the repo unless anyone has a better idea. :(

[shimizukawa]

From Thibault Kruse on 2013-01-30 12:25:54+00:00

+1

[shimizukawa]

From Georg Brandl on 2013-01-31 07:37:34+00:00

You can put it in the root and use ".. include:: ../README" from a file in "docs", like Sphinx does with CHANGES.

[shimizukawa]

From mears on 2013-08-27 06:48:18+00:00

I'd like to see this implemented as well

[shimizukawa]

From Adam Siembida on 2014-04-01 22:06:49+00:00

This would be great to have. I know you can use symlinks to files shared between projects, but Windows doesn't have the greatest support for that.

[dghubble]

I wish there was a way to put a relative link in a toctree entry too! I have some plain files (they happen to be javadocs, but could be anything generated by some non-sphinx system). I place files in the build directory with html_extra_path and tried adding a link to them in a number of ways:

.. toctree::
   :maxdepth: 2

   `javadoc/index.html`
    :ref:`javadoc/index.html`
    Javadoc <//javadoc/index.html>
    Javadoc <://javadoc/index.html>
    `Javadoc <javadoc/index.html>`
    self/javadoc/index.html
    :download:`javadoc/index.html`

Also tried with extlink, but none of these attempts seem to work.

Reading through the source, the simplest change might be to start treating // as the prefix for relative url and treating it specially in other.py and environment.py? The current implementation checks for a schema with re.compile(r'(?P<schema>.+)://.*') so I don't think relative links are possible right now.

Just want a relative anchor tag at the end of the day :(

[atodorov]

Basically me too.

I've tried:

:doc:`../tests/README.rst`

which didn't work of course.

[shimizukawa]

@atodorov

You can't use :doc: role in the toctree directive. You should write as:

.. toctree::

   ../tests/README

One more rule is exist.
You can not reference to out of sphinx project directory by using toctree directive (and :doc: role).